home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / b / iktker.lpt < prev    next >
Encoding:
Text File  |  1993-06-25  |  152.8 KB  |  2,467 lines

  1. 0
  2. 0
  3. 0
  4. 0
  5. 0
  6. 0
  7. 0
  8. 0
  9.                    IBM SYSTEM/370 MVS/TSO KERMIT USER'S GUIDE
  10. 0
  11.                                    VERSION 4.2
  12. 0
  13.                                   John Chandler
  14. 0                  Harvard/Smithsonian Center for Astrophysics
  15. 0                                 May 26, 1993
  16. 0
  17. 0                            Copyright (C) 1981,1993
  18.              Trustees of Columbia University in the City of New York
  19. 0     Permission is granted to any individual or institution to use, copy,
  20.      or redistribute this document so long as it is not sold for profit, and
  21.                    provided this copyright notice is retained.
  22. 1IBM System/370 Kermit                                                    Page i
  23. 0-------------------------------------------------------------------------------
  24.                                 Table of Contents
  25. 01. IBM 370 KERMIT                                                             1
  26. 0   1.1. Translation Tables                                                    2
  27.     1.2. File Attributes                                                       6
  28.     1.3. Program Operation                                                     7
  29.     1.4. Kermit-370 Subcommands                                                9
  30.     1.5. Before Connecting to the Mainframe                                   31
  31.     1.6. Trouble-shooting Protocol Converters                                 32
  32.     1.7. After Returning from Kermit-370                                      35
  33.     1.8. What's New                                                           36
  34.     1.9. What's Missing                                                       37
  35.     1.10. Further Reading                                                     38
  36. 02. IBM MVS/TSO KERMIT                                                        39
  37. 0   2.1. The MVS/TSO File System                                              40
  38.     2.2. Program Operation                                                    42
  39.     2.3. Kermit-TSO Subcommands                                               44
  40.     2.4. How to build an executable Kermit-TSO                                49
  41.     2.5. What's New                                                           50
  42.     2.6. What's Missing                                                       50
  43. 0Index                                                                        52
  44. 1IBM System/370 Kermit                                                   Page ii
  45. 0-------------------------------------------------------------------------------
  46.                                  List of Tables
  47. 0   Table 1-1:   Allowed character set combinations in Kermit-370              4
  48.     Table 1-2:   EBCDIC (hexadecimal) code points for LATIN1                   5
  49.     Table 1-3:   Character graphics for EBCDIC codes                           7
  50.     Table 1-4:   Error messages and codes for Kermit-370                      36
  51. 11. IBM 370 KERMIT                                                        Page 1
  52. 0-------------------------------------------------------------------------------
  53.  1. IBM 370 KERMIT
  54. 0Program:       John  Chandler  (Harvard/Smithsonian  Center  for Astrophysics);
  55.                 contributions from Vace Kundakci and Daphne Tzoar (Columbia  U),
  56.                 Bob  Shields  (U.  Maryland),  Greg  Small  (UC Berkeley), Clark
  57.                 Frazier (Harvard Bus. Sch.), Bob  Bolch  and  Steve  Blankinship
  58.                 (Triangle),  Ron  Rusnak  (U.  Chicago),  Roger  Fajman and Dale
  59.                 Wright (NIH), Andre Pirard (U. Liege),  Pierre  Goyette  (McGill
  60.                 U.)
  61.  Language:      IBM 370 Assembler
  62.  Documentation: John Chandler (CfA)
  63.  Version:       4.2.3
  64.  Date:          1993 May
  65. 0Kermit-370  is  a  family  of  programs  implementing  the KERMIT file transfer
  66.  protocol for IBM 370-series mainframes (System/370,  303x,  43xx,  308x,  3090,
  67.  etc.)  under  a  variety  of  operating  systems.    Kermit-370  operates  over
  68.  asynchronous ASCII communication lines attached to a 3705-style or protocol en-
  69.  veloping  3708  front  end  ("TTY" or line-mode devices), to a Series/1 or 4994
  70.  running the Yale ASCII Terminal Communication System  or  the  IBM  7171  ASCII
  71.  Device  Control Unit or a 9370 with ASCII subsystem ("SERIES1" devices), to the
  72.  IBM 3174 protocol converter at level B2.0 or  higher  ("AEA"  devices),  or  to
  73.  front-ends with graphics pass-through mode, such as the Datastream/Leedata 8010
  74.  and PCI 1076 ("GRAPHICS" devices).  As of this writing, the  pending  implemen-
  75.  tation  of  full(er)  7171 compatibility in the program product SIM3278 has not
  76.  been completed.    The  non-line-mode  devices  are  often  called  full-screen
  77.  devices.  For more details on front ends, see the section SET CONTROLLER.
  78. 0The  source is coded in IBM 370 assembly language and is compatible with the F,
  79.  VS, and H assemblers.  The code is divided into sections, some generic and some
  80.  specific  to  an individual operating system.  While the details of file-system
  81.  and supervisor interaction vary widely among  the  systems  available  for  IBM
  82.  370's, the basic features are essentially the same.  This chapter describes the
  83.  features common to all variants of Kermit-370, and a separate chapter will deal
  84.  with the system-specific details for each variant.
  85. 0IBM  370 systems have some peculiarities that users should be aware of.  First,
  86.  these systems are essentially half-duplex; the communication  line  must  "turn
  87.  around"  before  any  data  can  be  sent.    The  "TTY"  devices  are strictly
  88.  half-duplex, and even the "SERIES1", "GRAPHICS", and  "AEA"  devices,  although
  89.  they  maintain  full-duplex  communication  with  the terminal, must transmit a
  90.  block at a time to the mainframe.  The fact that a  packet  has  been  received
  91.  from the IBM system through a "TTY" device is no guarantee that it is ready for
  92.  a reply; generally, the true indicator of  readiness  is  the  line  turnaround
  93.  character  (XON), which the operating system sends immediately before issuing a
  94.  read request.  On some systems, however, it is possible for Kermit to  do  away
  95.  with  the  system-supplied  turnaround  and  schedule read requests immediately
  96.  after the corresponding writes.  It is up to the user to tell the other  Kermit
  97.  how it must conform to the requirements of the IBM mainframe.
  98. 0A  second distinction is that disk files are encoded using the EBCDIC character
  99.  set.  Consequently, there are three layers of character translation on  packets
  100.  exchanged  on  a  "TTY"  device.    For  an incoming packet, the outer layer is
  101.  provided by the operating system, which translates all characters from ASCII to
  102.  EBCDIC.    Kermit-370 must then translate the packets back to ASCII (the middle
  103.  layer) in order to calculate and verify the checksum.  Data arriving through  a
  104. 11. IBM 370 KERMIT                                                        Page 2
  105. 0-------------------------------------------------------------------------------
  106.  "SERIES1",  "GRAPHICS", or "AEA" device are still in ASCII and therefore bypass
  107.  the two outer layers.  In any case, Kermit-370 translates  text  files  finally
  108.  into  EBCDIC (the inner layer) before storing on disk.  When Kermit-370 sends a
  109.  file, the opposite translations occur.  The middle-layer tables used by  Kermit
  110.  must  be  the  inverses  of the corresponding outer-layer ones used by the host
  111.  operating system if file transfers are to work at all.  If necessary, the  sys-
  112.  tem  programmer  should  add the appropriate SET TATOE/TETOA/TTABLE subcommands
  113.  (q.v.)  to the global INIT file.  Indeed, it is usually  a  good  idea  to  set
  114.  TTABLE  ON  in  the  global INIT file to force using different built-in sets of
  115.  tables for the inner and middle layers whenever the system has  "TTY"  devices.
  116.  The standard 7-bit ASCII-to-EBCDIC translations can be found in the Appendix or
  117.  the IBM System/370 Reference Card.  See the section  "Translation  Tables"  for
  118.  more details.
  119. 0Another  distinction  of  IBM  370's  is  that they store and retrieve files as
  120.  records rather than byte streams.  Records may be either fixed-length with some
  121.  sort of padding (as needed) or varying-length with some sort of (generally hid-
  122.  den) delimiters.  Thus, Kermit-370 must assemble  incoming  data  packets  into
  123.  records  by  stripping  off carriage return-linefeed pairs (CRLF's) and padding
  124.  with blanks or truncating as needed and must strip trailing blanks  and  append
  125.  CRLF's to outgoing records.  (See the SET FILE TYPE subcommand.)  Further, disk
  126.  files typically have the records combined into blocks for efficiency.  One con-
  127.  sequence  of  this form of storage is that files have attributes describing the
  128.  component records: maximum record length (LRECL), record  format  (RECFM),  and
  129.  sometimes block size (BLKSIZE).
  130. 0As  mentioned before, Kermit-370 is a family of programs.  At present, only the
  131.  CMS, TSO, MUSIC, ROSCOE, and CICS variants are operational.  Variants for DOS-4
  132.  and MTS have at least reached the "drawing board," but no others have even been
  133.  started as of this writing.  Volunteers are always welcome to  port  Kermit-370
  134.  to  other operating systems or add new features to the existing family.  Anyone
  135.  interested should first get in touch with the Center for  Computing  Activities
  136.  at  Columbia  University  to find out what projects of a similar nature are al-
  137.  ready pending (and thereby prevent unnecessary duplication of effort).    There
  138.  are  supplemental  files in the Kermit distribution with explanations of how to
  139.  go about porting Kermit-370 and how to add support for new terminal  controller
  140.  types.    For  details, refer to the installation guide for the variant of your
  141.  choice.
  142. 0
  143.  1.1. Translation Tables
  144. 0Traditionally, IBM mainframe Kermits have translated 7-bit ASCII characters  to
  145.  8-bit   EBCDIC  characters  and  ignored  the  "parity"  bit  in  the  process.
  146.  Similarly, the 8-bit EBCDIC characters  have  been  mapped  onto  7-bit  ASCII,
  147.  thereby  producing  many  ambiguities  in  translating  the ASCII files back to
  148.  EBCDIC.  These ambiguities fall into  two  categories:  EBCDIC  characters  not
  149.  representable  in ASCII have been rendered as ASCII nulls, and alternate EBCDIC
  150.  representations of characters such as the  ASCII  backslash  have  been  mapped
  151.  together,  but  at  least no two 7-bit ASCII characters are translated into the
  152.  same EBCDIC character.  The ambiguities were tolerable  in  environments  where
  153.  the  traditionally  non-printable  characters never occurred in text files, but
  154.  text processing has increasingly tended to include such  characters  for  math-
  155.  ematical  formulas or for languages other than English.  Ultimately, the trans-
  156.  lation tables must become completely invertible, lest information  be  lost  in
  157.  the  transfer.    There  has long been an option to replace parts of the trans-
  158. 11.1. Translation Tables                                                  Page 3
  159. 0-------------------------------------------------------------------------------
  160.  lation tables via commands from the user (or imbedded in the INIT  files),  but
  161.  such  replacements were always supported locally and were, therefore, basically
  162.  non-standard.
  163. 0The concept of standard translations is currently in a state of flux because of
  164.  the  proliferation  of 8-bit code pages and the countervailing efforts at stan-
  165.  dardization among groups such as the ISO and Kermit developers.  In particular,
  166.  Kermit-370  now  supports  a set of EBCDIC and "extended ASCII" code pages with
  167.  built-in translation tables and automatic identification of the "ASCII"  trans-
  168.  fer  character  set via Attribute packets.  This facility supports files stored
  169.  using numerous IBM Country Extended Code  Pages  and  permits  transfers  using
  170.  character  sets  ASCII,  CYRILLIC,  GREEK, HEBREW, JAPAN-EUC, KATAKANA, LATIN1,
  171.  LATIN2, LATIN3, and THAI.  See Table 1-1 for a display of the allowed  combina-
  172.  tions  of  character  sets.  See also file ISOK7.TXT in the Kermit distribution
  173.  for a somewhat outdated description of the  protocol  extensions.    Kermit-370
  174.  currently supports text files in the following languages:  Afrikaans, Albanian,
  175.  Bulgarian, Byelorussian, Catalan,  Czech,  Croatian,  Danish,  Dutch,  English,
  176.  Esperanto,  Faeroese, Finnish, French, Gaelic, Galician, German, Greek, Hebrew,
  177.  Hungarian, Icelandic, Italian,  Japanese  (Katakana  and  Kanji),  Lao,  Latin,
  178.  Macedonian, Maltese, Norwegian, Polish, Portuguese, Quechua, Romanian, Russian,
  179.  Serbian, Slovak, Slovene, Spanish, Swahili, Swedish, Thai, Turkish,  Ukrainian,
  180.  and Volapuk.  Visual representations of the characters sets may be found in the
  181.  ISO register (for transfer) and in various IBM  documents,  such  as  S544-3156
  182.  "About Type" (for files).
  183. 0As  nearly as possible, the tables in Kermit-370 are invertible, but all of the
  184.  character sets reserve many (typically 65) code points for  control  characters
  185.  and  leave them officially undefined and unprintable.  This applies both to IBM
  186.  code pages and ISO standard 8-bit character sets.  Although 33 of the  controls
  187.  have widely accepted mappings, the others do not, and Kermit-370 currently uses
  188.  those given in an appendix of IBM's VS/Fortran Reference Manual.   Needless  to
  189.  say, such translations are arbitrary and may be invalidated by future decisions
  190.  at IBM or ISO.  Still, most of the translations are likely to be stable in  the
  191.  long run.  Table 1-2 shows the current translation from LATIN1 to EBCDIC, which
  192.  is likely to be the most often used.  Other translations, including the reverse
  193.  ones, may be displayed using the TDUMP subcommand of Kermit-370.
  194. 0Besides converting files for transmission, Kermit-370 must also  compensate for
  195.  the EBCDIC/ASCII translation performed by some front ends and must,  therefore,
  196.  be able to apply the exact reverse translations on both input and output.  This
  197.  is the "middle layer" of translation described earlier for "TTY" devices.  Con-
  198.  sider  the  fate  of  a Left Square Bracket character in an inbound packet on a
  199.  "TTY" line.  It begins as ASCII code x'5B' (91  decimal),  but  the  front  end
  200.  translates  it  to EBCDIC before presenting it to Kermit-370.  In this example,
  201.  suppose it becomes EBCDIC code x'4A' (74 decimal) instead of the standard x'AD'
  202.  (173  decimal).    Then,  Kermit must be primed with a SET TETOA 74 91 so that,
  203.  when reconstructing the original ASCII  packet,  the  character  becomes  x'5B'
  204.  again.   Otherwise, the packet checksum will appear invalid.  Kermit comes with
  205.  a pair of default tables, but it may be necessary to customize  them,  as  this
  206.  example  shows.    The following procedure will reveal any changes needed.  The
  207.  procedure has two stages: the first is for any line-mode  front  end,  and  the
  208.  second only for front ends capable of full 8-bit data transfer.  Note that, al-
  209.  though the discussion refers to hexadecimal values, the Kermit-370 SET  subcom-
  210.  mands  require  decimal  numeric arguments.  Also, note that this procedure as-
  211.  sumes you will run  Kermit  with  TTABLE  set  on;  hence,  the  references  to
  212.  Kermit-370  tables  are  to  TATOE and TETOA.  If you choose to define Kermit's
  213. 11.1. Translation Tables                                                  Page 4
  214. 0-------------------------------------------------------------------------------
  215.  -------------------------------------------------------------------------------
  216. 0
  217.                              Transfer character set
  218. 0  Local  ASCII CYRILLIC GREEK HEBREW JAPAN KATAK.  L1 L2 L3 THAI
  219. 0 CP037     *                                       **
  220.   CP273                                             **
  221.   CP275                                             **
  222.   CP277                                             **
  223.   CP278                                             **
  224.   CP280                                             **
  225.   CP281                                 *           **
  226.   CP282                                             **
  227.   CP284                                             **
  228.   CP285                                             **
  229.   CP290                                 *     **
  230.   CP297                                             **
  231.   CP424                          **
  232.   CP500     *                           *           **
  233.   CP838                                                       **
  234.   CP870                                                **
  235.   CP871                                             **
  236.   CP875                    **
  237.   CP880     *      **
  238.   CP905                                                   **
  239.   CZECH                                                 *
  240.   DKOI      *      ***
  241.   EBCDIC    **                                     ***
  242.   H-EBCD                                *      *
  243.   KANJI                                 *
  244. 0         Table 1-1:  Allowed character set combinations in Kermit-370
  245. 0All   allowed  combinations  are  marked  with  asterisks,  and  the  preferred
  246.  combination in each row or column is the one with the most asterisks.  Whenever
  247.  a  character  set is specified, either directly or through an Attribute packet,
  248.  the other category of character set is checked to see if it makes up an allowed
  249.  combination.  If not, it is forced to the preferred character set.
  250. 0
  251.  -------------------------------------------------------------------------------
  252. 0file translation to match that of the front end, you should  leave  TTABLE  set
  253.  off  and  remove  the  T's from the SET subcommands described below.  This will
  254.  also turn off the automatic switching of translation tables  according  to  the
  255.  Attribute  packets received from the other Kermit.  Under CMS, you must issue a
  256.  CMS SET INPUT and a CMS SET OUTPUT before starting this procedure.
  257. 0   1. Create a file containing all the non-control EBCDIC characters  (hex
  258.        codes  40-FF)  and  display the file on any available ASCII terminal
  259.        hooked up to the line-mode front end in question.
  260. 0   2. If any printable ASCII character is missing from the display, Kermit
  261.        cannot  work through this front end (unless you modify the tables in
  262. 11.1. Translation Tables                                                  Page 5
  263. 0-------------------------------------------------------------------------------
  264.  -------------------------------------------------------------------------------
  265. 0
  266.        -0 -1 -2 -3 -4 -5 -6 -7 -8 -9 -A -B -C -D -E -F
  267. 0  0-  00 01 02 03 37 2D 2E 2F 16 05 25 0B 0C 0D 0E 0F
  268.    1-  10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F
  269.    2-  40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
  270.    3-  F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
  271.    4-  7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
  272.    5-  D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D
  273.    6-  79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
  274.    7-  97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 07
  275.    8-  20 21 22 23 24 15 06 17 28 29 2A 2B 2C 09 0A 1B
  276.    9-  30 31 1A 33 34 35 36 08 38 39 3A 3B 04 14 3E FF
  277.    A-  41 AA 4A B1 9F B2 6A B5 BB B4 9A 8A B0 CA AF BC
  278.    B-  90 8F EA FA BE A0 B6 B3 9D DA 9B 8B B7 B8 B9 AB
  279.    C-  64 65 62 66 63 67 9E 68 74 71 72 73 78 75 76 77
  280.    D-  AC 69 ED EE EB EF EC BF 80 FD FE FB FC BA AE 59
  281.    E-  44 45 42 46 43 47 9C 48 54 51 52 53 58 55 56 57
  282.    F-  8C 49 CD CE CB CF CC E1 70 DD DE DB DC 8D 8E DF
  283. 0
  284.              Table 1-2:  EBCDIC (hexadecimal) code points for LATIN1
  285. 0This  table  shows  the values of the EBCDIC equivalents for the code points in
  286.  the LATIN1 character  set.    The  values  are  arranged  in  LATIN1  collating
  287.  sequence,  and  the  rows  and  columns  are  labeled with the first and second
  288.  digits, respectively, of the LATIN1 code points.  For example, LATIN1  code  41
  289.  (hex)  is  upper-case "A", and the intersection of row "4-" and column "-1" has
  290.  the value C1 (hex), which is the EBCDIC code for "A".  Rows "0-",  "1-",  "8-",
  291.  and  "9-" are officially undefined in ISO 8859-1 and so, in principle, could be
  292.  changed at some future time, especially "8-" and "9-".  Note  that  this  table
  293.  uses  a  format  close  to  that of the TDUMP subcommand and of the Kermit code
  294.  itself, but character-set tables are often displayed with the rows and  columns
  295.  interchanged.
  296. 0
  297.  -------------------------------------------------------------------------------
  298. 0      the front end itself).
  299. 0   3. If any ASCII character appears twice, there is no cause for alarm.
  300. 0   4. If any ASCII character does not appear where it should, according to
  301.        Table  1-3,  a SET TATOE must be added to the system INIT file.  For
  302.        example, if EBCDIC code 5F (Not Sign, according to the Appendix) ap-
  303.        pears  as an ASCII Tilde (7E), but EBCDIC A1 (Tilde) does not, a SET
  304.        TATOE 126 95 is required.  Warning: characters  considered  unprint-
  305.        able  by  the  front end are likely to be filtered out entirely when
  306.        you display the file; do not expect the display to line up just like
  307.        Table 1-3.
  308. 0   5. Create  a  file  on the mainframe using an ASCII terminal for input,
  309.        and enter all 95 printable ASCII characters in  collating  sequence.
  310.        You  can  presumably  save  time  by  skipping  the  52  upper-  and
  311. 11.1. Translation Tables                                                  Page 6
  312. 0-------------------------------------------------------------------------------
  313.        lower-case letters and the 10 digits.
  314. 0   6. Display the file from the previous step in hexadecimal or other  bi-
  315.        nary form.
  316. 0   7. If any duplicates appear among the 95 characters (or 33, if you have
  317.        taken the short cut), Kermit cannot work through this front end (un-
  318.        less you modify the tables in the front end).
  319. 0   8. Compare the hexadecimal codes with rows 2-7 of Table 1-2.  If a dis-
  320.        crepancy appears, a SET TETOA must be added to the system INIT file.
  321.        For  example, if ASCII Left Bracket (5B) appears as EBCDIC 4A, a SET
  322.        TETOA 74 91 is needed.  At this point, the first stage is complete.
  323. 0   9. If 8-bit line-mode file transfer is desired, you must now verify the
  324.        extended  character  set.    Display the file of EBCDIC codes again,
  325.        this time using a terminal with extended character set  display,  or
  326.        capture  the  session  with a micro Kermit and display the resulting
  327.        file in hexadecimal.  If any code in the range A0-FE  does  not  ap-
  328.        pear,  the  front  end  will  not allow 8-bit Kermit data transfers.
  329.        Generate SET TATOE entries for the entire range, as needed, just  as
  330.        in  the  example  given  for 7-bit codes.  If the front end's trans-
  331.        lation tables are documented, it may be  easier  to  work  from  the
  332.        manual,  but  you  must  be sure that you have tables for all of the
  333.        translations that occur on the data path.
  334. 0  10. Create a file of the 95 extended ASCII codes A0-FE, if possible,  by
  335.        using a terminal capable of transmitting those codes or transmitting
  336.        a pre-made file "raw".  If necessary, use the  appropriate  table(s)
  337.        in the manual(s) instead.
  338. 0  11. Again,  if  any  duplicates  appear,  this front end is incapable of
  339.        8-bit file transfers.  Otherwise, generate SET TETOA entries as  be-
  340.        fore.
  341. 0
  342.  1.2. File Attributes
  343. 0Kermit-370  attempts  to  send and receive file attributes along with the files
  344.  themselves.  Before Kermit receives a file, it compares  the  Length  attribute
  345.  (if  available)  with the amount of disk space available (if known) so that the
  346.  file can be rejected if it will not fit.  In addition, the Type, Access, Encod-
  347.  ing,  Disposition,  and  Format attributes, if any, are interpreted in order to
  348.  match the received file to the original as nearly as possible.  All  other  at-
  349.  tributes (including Date) are simply ignored.  For Type, Kermit recognizes text
  350.  and binary specifications; for Access, it recognizes append, normal, and super-
  351.  sede;  for Encoding, it recognizes ASCII, extended, and EBCDIC (which it treats
  352.  as binary); for Disposition, it recognizes mail, print, and job; and  for  For-
  353.  mat,  it  recognizes  text,  D-binary,  V-binary, binary, and LRECL.  Any other
  354.  values are rejected.
  355. 0On sending a file, if the other Kermit is willing to accept Attribute  packets,
  356.  Kermit-370  sends  the Type, Encoding, Format, Date, and Length attributes (un-
  357.  less some or all of them have been disabled -- see the  SET  ATTRIBUTE  subcom-
  358.  mand).
  359. 0Unfortunately, the set of file attributes defined in the Kermit protocol is not
  360. 11.2. File Attributes                                                     Page 7
  361. 0-------------------------------------------------------------------------------
  362.  -------------------------------------------------------------------------------
  363. 0
  364.         0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
  365. 0  4-                                    .  <  (  +  |
  366.    5-   &                             !  $  *  )  ;  ^
  367.    6-   -  /                             ,  %  _  >  ?
  368.    7-                              `  :  #  @  '  =  "
  369.    8-      a  b  c  d  e  f  g  h  i
  370.    9-      j  k  l  m  n  o  p  q  r
  371.    A-      ~  s  t  u  v  w  x  y  z           [
  372.    B-                                          ]
  373.    C-   {  A  B  C  D  E  F  G  H  I
  374.    D-   }  J  K  L  M  N  O  P  Q  R
  375.    E-   \     S  T  U  V  W  X  Y  Z
  376.    F-   0  1  2  3  4  5  6  7  8  9
  377. 0
  378.                  Table 1-3:  Character graphics for EBCDIC codes
  379. 0This  table  shows  the  representations of the EBCDIC codes arranged in EBCDIC
  380.  collating sequence, row by row.  Codes  that  do  not  correspond  to  ISO  646
  381.  characters (7-bit ASCII), have been left blank.  One special case is the EBCDIC
  382.  code 5F, which represents a Not Sign in IBM's CP037, but which is traditionally
  383.  mapped  to  the ASCII Circumflex, as shown here.  WARNING: this manual may have
  384.  been printed on a  device  that  maps  characters  differently.    Consult  the
  385.  Appendix to verify.
  386. 0
  387.  -------------------------------------------------------------------------------
  388. 0well matched to the needs of  IBM  370  file  systems,  so  that  much  of  the
  389.  machinery  for  creating and interpreting of Attribute packets is useless.  For
  390.  example, the "Format" attribute, which should logically specify the record for-
  391.  mat of the received file, gives only the format of the file in transmission and
  392.  cannot distinguish between fixed-length and  varying-length  records  for  text
  393.  files.    This  limitation  is partly due to the fact that other Kermits do not
  394.  generally support the same attributes.  In short, even if the protocol made  it
  395.  possible,  some  of  the  important attributes would never be specified anyway.
  396.  Nonetheless, efforts are being made to extend the  protocol  to  be  more  com-
  397.  prehensive.
  398. 0
  399.  1.3. Program Operation
  400. 0Kermit-370  can  be  invoked  directly  or from a command procedure.  In either
  401.  case, it reads and executes subcommands sequentially until  directed  to  quit,
  402.  and  then  returns.    A  subcommand  consists  of  one  or more fields (words)
  403.  separated by spaces or commas.
  404. 0Upon startup, the program looks for two (optional)  initialization  files,  one
  405.  system-wide  and a second specific to the user.  Both filespecs are, of course,
  406.  system-dependent.  The purpose of these files is to allow  Kermit  to  be  cus-
  407.  tomized  for  a  particular  system  and for a user's specific settings without
  408.  changing the source code.  The system-wide file, which is maintained by a  sys-
  409. 11.3. Program Operation                                                   Page 8
  410. 0-------------------------------------------------------------------------------
  411.  tems programmer, should contain Kermit subcommands that all users would need to
  412.  issue in order for Kermit to run on the system, such as subcommands  to  modify
  413.  the  ASCII/EBCDIC  tables  used by Kermit-370.  The user-specific file, if any,
  414.  should contain subcommands that the user generally issues every time Kermit  is
  415.  run.    Kermit-370 executes any subcommands found in these files as though they
  416.  were typed at the terminal.  Here is a sample INIT file:
  417. 0  * Asterisk in column one is a comment.
  418.    set transfer character-set latin1
  419.    set file collision rename
  420.    set block 3
  421. 0During interactive execution, you may  use  the  built-in  help  feature  while
  422.  typing Kermit-370 subcommands.  A question mark ("?") typed at almost any point
  423.  in a subcommand, followed by a carriage return, produces a brief description of
  424.  what  is  expected or possible at that point.  Moreover, mistyping a subcommand
  425.  will generally produce a helpful error message or a list of possible options at
  426.  the   point  of  error.    Keywords  in  such  lists  are  displayed  with  the
  427.  minimum-length abbreviation in upper case and the remainder, if any,  in  lower
  428.  case.  In entering Kermit subcommands, any keyword may be shortened to any sub-
  429.  string that contains the minimum abbreviation.
  430. 0Besides knowing the mechanics of entering Kermit subcommands  and  interpreting
  431.  responses,  the  user  must  understand  which  subcommands are necessary.  The
  432.  default values for Kermit-370 options have, in some cases, been constrained  by
  433.  a  desire  for  continuity,  so that some of the default behavior is distinctly
  434.  "suboptimal."  An example of this is the traditional  80-byte  default  RECEIVE
  435.  packet size, which generally gives much slower transmission than a size of 1000
  436.  or more.  Such options are flagged in this chapter with a  notation  that  they
  437.  perhaps  ought  to be set in the INIT files.  Note, however, that the interplay
  438.  of Kermit protocol sometimes provides a performance upgrade with no special ac-
  439.  tion  required  from  the  Kermit-370  user.    An  example of this is the SEND
  440.  packet-size, which is always under the control of the other Kermit.  Kermit-370
  441.  always  sends  packets as long as the other Kermit allows, unless the frequency
  442.  of transmission errors indicates that shorter packets would be  more  efficient
  443.  (see the subcommand SET SPEED).
  444. 0Kermit-370 also attempts to produce optimal results by adapting to the file at-
  445.  tributes sent by the other Kermit along with the files, such as TYPE and LRECL.
  446.  Such  attributes,  when sent by the other Kermit, temporarily override the cur-
  447.  rent settings in Kermit-370  during  the  reception  of  the  associated  file.
  448.  Potentially  even  more  importantly,  Kermit-370  automatically recognizes the
  449.  character set used for the file transfer and  chooses,  if  necessary,  a  com-
  450.  patible  character  set  for  file storage.  Table 1-1 shows the currently sup-
  451.  ported list of character sets.   As  with  any  automatic  operation,  Kermit's
  452.  honoring of the transmitted attributes may need to be suppressed in part or al-
  453.  together, and the SET ATTRIBUTE subcommand provides this capability.
  454. 0Another attribute that Kermit-370 supports is file  disposition,  which  allows
  455.  files  to be received and immediately retransmitted as electronic mail, sent to
  456.  a printer, or submitted as a  batch  job.    These  three  options  are  highly
  457.  site-specific  and are implemented as a set of three host commands with similar
  458.  calling sequences.  In each case, the command is invoked in two different  ways
  459.  in  the  process  of processing the file.  It is called without any filespec or
  460.  other  options  as  soon  as  the  corresponding  attribute  is  recognized  by
  461.  Kermit-370.    If  the  command is not implemented or for some reason returns a
  462. 11.3. Program Operation                                                   Page 9
  463. 0-------------------------------------------------------------------------------
  464.  non-zero completion code (such a code should be negative, if at all  possible),
  465.  Kermit-370  rejects  the  file  using  the normal attribute exchange mechanism.
  466.  Otherwise, the file is received as usual, and the command is invoked  again  at
  467.  the  end-of-file.    The  second  time,  the  command  is given the name of the
  468.  received file and the options received from the sending  Kermit  (such  as  the
  469.  list  of  recipients for electronic mail).  The command is then responsible for
  470.  disposing of the file (and deleting it, if desired).  If, for any  reason,  the
  471.  file  cannot  be sent as required, the command should return a negative comple-
  472.  tion code (or non-zero, at any rate), and Kermit-370 will send  back  an  error
  473.  message  to the sending Kermit.  The command itself should refrain from issuing
  474.  any messages of its own or permitting commands that it invokes  to  issue  mes-
  475.  sages.    See  the  beginning  of the chapter on the system-specific variant of
  476.  Kermit-370 for the exact command syntax.  Some sample implementations  of  such
  477.  commands  may  be  available  in  the  Kermit  distribution  --  refer  to  the
  478.  system-specific installation guide for a list of samples.
  479. 0
  480.  1.4. Kermit-370 Subcommands
  481. 0The following is a summary of Kermit subcommands.  The starred subcommands  can
  482.  be  issued  as  remote Kermit commands to Kermit-370 when it is in server mode.
  483.  System-specific subcommands are omitted from this list.
  484. 0          BYE      logs out other Kermit server.
  485.            CWD*     establishes a new working directory.
  486.      DIRECTORY      displays all or part of the disk directory.
  487.           ECHO      a line back to the user.
  488.           EXIT      from Kermit-370.
  489.         FINISH      other Kermit server.
  490.            GET      file(s) from a Kermit server.
  491.           GIVE*     creates a TAKE file snapshot of a table.
  492.           HELP      about Kermit-370.
  493.           HOST*     executes a system command.
  494.         KERMIT*     executes a Kermit subcommand.
  495.           QUIT      from Kermit-370.
  496.        RECEIVE      file(s) from other Kermit.
  497.           SEND      file(s) to other Kermit.
  498.         SERVER      mode of remote operation.
  499.            SET*     various parameters.
  500.           SHOW*     various parameters.
  501.          SPACE*     displays disk storage allocation.
  502.         STATUS*     inquiry.
  503.           STOP      easy escape from protocol mode.
  504.           TAKE*     subcommands from file.
  505.          TDUMP*     dumps the contents of a table.
  506.           TYPE*     a file.
  507.          XECHO      echoes a line (transparently).
  508.          XTYPE      displays a file (transparently).
  509. 0Although Kermit-370 is generally a remote Kermit, it has the capability of com-
  510.  municating  with  another  Kermit  in  server  mode.    In  that situation, the
  511.  subcommand prefixes REMOTE and LOCAL refer to the Kermit server and Kermit-370,
  512.  respectively,  even  when  Kermit-370 is, strictly speaking, the remote Kermit.
  513.  To help avoid confusion, this chapter will often  use  the  term  "foreign"  to
  514.  apply  to  the  Kermit at the other end from Kermit-370.  All the above subcom-
  515.  mands may be preceded by the LOCAL prefix, but only certain ones are valid with
  516. 11.4. Kermit-370 Subcommands                                             Page 10
  517. 0-------------------------------------------------------------------------------
  518.  REMOTE,  including some not shown here.  See the description of the SERVER sub-
  519.  command for details.  Any text replies Kermit-370 gets from the foreign  Kermit
  520.  server   are   added   to   a   disk   file  (whose  filespec  is,  of  course,
  521.  system-dependent).  Such a transaction can be carried out, for  example,  under
  522.  control  of  a  TAKE file if Kermit-370 is not operating locally.  If the local
  523.  Kermit has a "magic" character sequence that switches it from  terminal  emula-
  524.  tion  to  server  mode,  then  an  entire  session could be controlled from the
  525.  mainframe, possibly in response to a single command issued  by  a  naive  user.
  526.  For example,
  527. 0  .grab
  528. 0       Kermit-370 is invoked and executes the following TAKE file
  529. 0  ECHO Serve Me!        the local Kermit switches to server mode
  530.    GET file.a            the server uploads file.a
  531.    FINISH                the server switches back to terminal mode
  532. 0The remainder of this section describes subcommands with special meaning or use
  533.  in Kermit-370, except the highly system-dependent ones.  For the latter,  refer
  534.  to the appropriate chapter.  Subcommands are listed in alphabetical order.
  535. 0
  536.                          THE ECHO AND XECHO SUBCOMMANDS
  537. 0Syntax: [X]ECHO line
  538. 0These subcommands type the line back at the user.  The line may contain control
  539.  characters or any desired text, including upper or lower case.   These  subcom-
  540.  mands may be used, for example, to test the ASCII/EBCDIC translate tables or to
  541.  issue coded commands to the user's terminal.  XECHO differs from ECHO primarily
  542.  in  that  it sends the text as a raw transmission according to the current CON-
  543.  TROLLER setting.  Thus, XECHO will, if necessary, break the text into pieces no
  544.  larger  than the current SEND PACKET-SIZE and will use transparent mode if CON-
  545.  TROLLER is SERIES1, GRAPHICS  or  AEA.    It  also  offers  its  own  brand  of
  546.  control-character  quoting,  using  the "^" character to indicate that only the
  547.  five low-order bits of the ASCII codes are to be used.  Thus, "^a",  "^A",  and
  548.  "^!"  are  all  translated  to  SOH (CTRL-A), while "^[" becomes ESC.  However,
  549.  there must be one exception for "^" itself: "^>" and "^~" are  both  translated
  550.  to RS (CTRL-^), but "^^" becomes just "^".  XECHO also decodes 8th-bit quoting,
  551.  just as in Kermit protocol, and this feature can be disabled by setting 8th-bit
  552.  quoting  off.  For example, if the 8th-bit quote character is "&", entering the
  553.  subcommand "XECHO &A" will transmit a code x'C1', but the same subcommand  with
  554.  quoting off will transmit two bytes: x'2641'.
  555. 0
  556.                                THE GET SUBCOMMAND
  557. 0Syntax: GET [foreign-filespec [filespec]]
  558. 0The  GET subcommand tells Kermit to request a file or file group from the other
  559.  system, which must have a Kermit running in server mode.   Provided  the  other
  560.  Kermit  complies,  the  effect is the same as if SEND foreign-filespec had been
  561.  issued directly to the other Kermit and RECEIVE [filespec] to Kermit-370.    If
  562.  this  subcommand  is  issued  without any arguments, Kermit-370 will prompt the
  563.  user for both foreign and native filespecs (and  will  insist  on  getting  the
  564. 11.4. Kermit-370 Subcommands                                             Page 11
  565. 0-------------------------------------------------------------------------------
  566.  former,  but  will do without the latter).  See the respective SEND and RECEIVE
  567.  subcommands for a description of the each filespec.
  568. 0
  569.                                THE GIVE SUBCOMMAND
  570. 0Syntax: GIVE table-name filespec
  571. 0This compares the named translation table with its current default  values  and
  572.  saves  the differences in the form of a TAKE file consisting of SET subcommands
  573.  that would convert the default into  the  current  arrangement.    ATOE,  ETOA,
  574.  TATOE,  and  TETOA  are  the available tables.  The details of the filespec are
  575.  system-dependent, but those details will, in general, be the same  as  for  the
  576.  TAKE  subcommand  (q.v.).    In  the  case of tables ATOE and ETOA, the current
  577.  defaults are the values from the most recent character-set definition, if  any,
  578.  but  the defaults for TATOE and TETOA always remain at the initial values.  See
  579.  the SET FILE CHARACTER-SET and SET TRANSFER CHARACTER-SET subcommands for  more
  580.  details.
  581. 0
  582.                               THE HINTS SUBCOMMAND
  583. 0Syntax: HINTS
  584. 0This  subcommand  produces a screenful of suggestions for Kermit operation, in-
  585.  cluding warnings about any current settings that may be undesirable.
  586. 0
  587.                                THE HOST SUBCOMMAND
  588. 0Syntax: HOST text of command
  589. 0This issues a command to the host operating system from  Kermit-370.    When  a
  590.  command  returns  a  non-zero  completion  code,  the  code  will be displayed.
  591.  Generally, the name of the system (e.g., CMS) is treated as a synonym  for  the
  592.  HOST subcommand.
  593. 0When  Kermit-370  is  in (non-local) server mode, you must avoid sending it any
  594.  HOST commands that trigger full-screen terminal I/O,  since  the  server-client
  595.  interface   does  not  provide  any  full-screen  terminal  emulation,  nor  is
  596.  Kermit-370 usually able to intercept such I/O in any case.
  597. 0
  598.                               THE KERMIT SUBCOMMAND
  599. 0Syntax: KERMIT text of subcommand
  600. 0This is provided for redundancy as the  counterpart  of  the  HOST  subcommand.
  601.  Kermit-370  executes  the  specified text as a Kermit subcommand just as if the
  602.  LOCAL prefix had been entered.  Note, however, that the specified text must not
  603.  begin with a second KERMIT prefix.
  604. 11.4. Kermit-370 Subcommands                                             Page 12
  605. 0-------------------------------------------------------------------------------
  606.                              THE RECEIVE SUBCOMMAND
  607. 0Syntax: RECEIVE [filespec]
  608. 0The  RECEIVE  subcommand  tells Kermit-370 to accept a file or file group.  The
  609.  user must issue the corresponding SEND subcommand to the other  Kermit.    When
  610.  files are received, their names are recorded in a transaction log in memory and
  611.  may be viewed later via the TDUMP NAMES subcommand.  The log contains the names
  612.  along with the file sizes and any relevant error messages.  Another form of log
  613.  may be provided through an accounting exit routine, which is called at the  end
  614.  of  every RECEIVE session.  Such an accounting log may contain elapsed time and
  615.  numbers of bytes sent, received, and transferred to/from disk.  If an error oc-
  616.  curs  during the file transfer, as much of the file as was received is saved on
  617.  disk.  If, however, the sending of a file is  cancelled  by  the  user  of  the
  618.  foreign  system, Kermit-370 will discard whatever had arrived, unless FILE COL-
  619.  LISION is APPEND or INCOMPLETE is KEEP.
  620. 0Kermit-370 has a context-dependent maximum record length, and received  records
  621.  longer  than  that  will be folded or truncated to the proper length; when this
  622.  happens, Kermit may or  may  not  stop,  depending  on  the  FILE  subparameter
  623.  LONGLINE.   If truncation does occur, Kermit will later note the fact as an er-
  624.  ror (unless something more serious happens in the meantime).  In addition, when
  625.  a  fixed record length is specified, received records are padded to the correct
  626.  length.  The padding character is a blank for text files and a null for  binary
  627.  files.    Received  binary  (but not V-binary or D-binary) files are treated as
  628.  byte streams and broken up into records all of the logical record length, i.e.,
  629.  folded.    For more details on the RECEIVE subcommand syntax and operation, see
  630.  the chapter on the desired system-specific variant  of  Kermit-370  under  both
  631.  RECEIVE and SET FILE.  See also (in this chapter) the SET FILE LONGLINE subcom-
  632.  mand for details on record truncation and folding.
  633. 0
  634.                                THE SEND SUBCOMMAND
  635. 0Syntax: SEND [filespec[<options>] [foreign-filespec]][, ...]
  636. 0The SEND subcommand tells Kermit-370 to send a file or file group to the  other
  637.  (foreign)  Kermit.  If no such file exists, Kermit-370 simply displays an error
  638.  message and issues another prompt.  Like RECEIVE, SEND keeps a transaction  log
  639.  of  all  files  transferred in a group and calls the accounting exit routine at
  640.  the end of the session.  If this subcommand is issued  without  any  arguments,
  641.  Kermit-370 will prompt the user for both native and foreign filespecs (and will
  642.  insist on getting the former, but will do without the latter).  Either with  or
  643.  without  prompting,  SEND  allows  specifying a list of up to 13 files (or file
  644.  groups) separated by commas.    (By  ending  the  command  line  or  subsequent
  645.  response  with  a  comma, the user ensures further prompting.)  In this syntax,
  646.  the options enclosed in angle brackets may be regarded as part  of  the  native
  647.  filespec.  There must be no intervening blanks.  At present, the only supported
  648.  option is a range of line numbers within the file to be sent.  The range  takes
  649.  the  form  [n][-[m]], where n is the number of the first line to send (counting
  650.  from 1), and m is the last.  Omitting either number implies  the  corresponding
  651.  limit  is  the  physical beginning or end of the file.  This same option syntax
  652.  may be used in some commands issued to the foreign Kermit,  namely,  those  in-
  653.  volving filespecs in 370 form.  In particular, GET and REMOTE TYPE can use this
  654.  syntax.  Note that a trailing ">" is  used  by  some  other  Kermits,  such  as
  655.  MS-Kermit,  to indicate redirection of the output from REMOTE commands to disk.
  656. 11.4. Kermit-370 Subcommands                                             Page 13
  657. 0-------------------------------------------------------------------------------
  658.  In order to transmit the ">" and also prevent the redirection to disk, it would
  659.  be necessary to add an explicit redirection to the terminal, as in
  660. 0  REM TYPE filespec<n-m> > CON
  661. 0Although  file  transfers  cannot be cancelled from the 370 side, Kermit-370 is
  662.  capable of responding to "cancel file" or "cancel batch" signals from the local
  663.  Kermit; these are typically entered by typing CTRL-X or CTRL-Z, respectively.
  664. 0When Kermit-370 sends files using long packets (longer than 94), the throughput
  665.  is especially sensitive to the level of noise on the line because  retries  are
  666.  so  time-consuming.    Therefore,  Kermit-370  imposes an extra, heuristic size
  667.  limit on packets when retries have been found necessary.    When  that  is  the
  668.  case,  after  every  15  packets,  Kermit  computes the packet size for maximum
  669.  throughput  assuming  that  the  transmission  errors  were  due   to   sparse,
  670.  Poisson-distributed  noise bursts.  The result of this calculation is then used
  671.  as another limit on the size of outgoing packets besides the one  specified  by
  672.  the other Kermit.  If no retries are required, then Kermit-370 assumes the line
  673.  to be noiseless and sends packets of the maximum length the  other  Kermit  al-
  674.  lows.   The algorithm is explained in Kermit News V. 3 #1.  For more details on
  675.  the SEND subcommand syntax and  operation,  see  the  chapter  on  the  desired
  676.  system-specific variant of Kermit-370.
  677. 0
  678.                               THE SERVER SUBCOMMAND
  679. 0Kermit-370  is  capable  of acting as a server.  In server mode, Kermit-370 can
  680.  send and receive files, execute host commands, execute a restricted set of Ker-
  681.  mit  subcommands,  and perform a variety of generic Kermit functions.  The fol-
  682.  lowing list shows the typical local Kermit commands along with the server func-
  683.  tions  they  elicit.    When Kermit-370 is talking to another Kermit running in
  684.  server mode, these same subcommands may be used in the other direction.
  685. 0BYE                 log out the Kermit server.
  686.  FINISH              server mode.
  687.  GET                 a file or files from the server.
  688.  REMOTE
  689.    COPY              a file or files.
  690.    CWD               set new working directory.
  691.    DELETE            a file or files.
  692.    DIRECTORY         display file attributes.
  693.    HELP              display a command summary, such as this.
  694.    HOST              execute a system command.
  695.    KERMIT            execute a Kermit-370 subcommand.
  696.    PRINT             send a file to be printed by the server.
  697.    RENAME            a file or files.
  698.    SPACE             display disk space.
  699.    TYPE              a file.
  700.  SEND                a file or files to the server.
  701. 0If your local Kermit does not support the REMOTE KERMIT command, you  may  need
  702.  to  issue  SET  subcommands  to select various options before typing the SERVER
  703.  subcommand.  Once in server mode, Kermit-370 will await  all  further  instruc-
  704.  tions  from the client Kermit on the other end of the connection until a FINISH
  705.  or BYE command is given.
  706. 0Command execution in server mode is different  in  some  respects  from  normal
  707. 11.4. Kermit-370 Subcommands                                             Page 14
  708. 0-------------------------------------------------------------------------------
  709.  operation.  First of all, some Kermit subcommands are not allowed (see the list
  710.  at the beginning of this section).  Moreover, command errors  always  terminate
  711.  any  active  TAKE file.  Also, all commands will be run in the special environ-
  712.  ment that Kermit sets up during protocol transfers.  Among other things, Kermit
  713.  intercepts  all  terminal  I/O  (if  possible)  in this environment in order to
  714.  transmit the data to the local Kermit as text packets.
  715. 0Note that some operations can be requested by several different commands.    If
  716.  for  example,  the  IBM 370 system has a command "PRT" for displaying a file, a
  717.  user interacting with a Kermit-370 server can choose to display a file  by  is-
  718.  suing  any  of  the commands: REMOTE TYPE, REMOTE HOST PRT, REMOTE KERMIT TYPE,
  719.  REMOTE KERMIT HOST PRT, or (if SYSCMD has been set ON) REMOTE KERMIT PRT.   The
  720.  first  form  simply transfers the requested file as text, but the others invoke
  721.  the "PRT" command with any specified options, intercept  the  terminal  output,
  722.  and  return  the  results  to the local Kermit.  The first form is also distin-
  723.  guished by the fact that the line range may be specified in the same manner  as
  724.  in the SEND subcommand.  The syntax of the others is system-dependent.
  725. 0
  726.                                THE SET SUBCOMMAND
  727. 0Syntax: SET parameter [value]
  728. 0The  SET subcommand establishes or modifies various parameters controlling file
  729.  transfers.  The values can, in turn, be  examined  with  the  SHOW  subcommand.
  730.  Some  parameters  have two levels.  In particular, there are two matching lists
  731.  of SEND and RECEIVE sub-parameters corresponding to  the  values  exchanged  by
  732.  Kermits  in  the  Send-Init/ACK sequence.  For each of these SEND/RECEIVE pairs
  733.  one element is encoded in outgoing parameter packets, and the other is  decoded
  734.  from incoming ones.  Setting the latter by hand may be needed to establish con-
  735.  tact and also has the effect of redefining the default value for decoding  from
  736.  subsequent  parameter  packets.    Generally,  the distinction between SEND and
  737.  RECEIVE parameters is unambiguous, the only  exception  being  TIMEOUT  (q.v.).
  738.  The following SET subcommands are available in Kermit-370:
  739. 0ATOE                Modify the Kermit-370 ASCII-to-EBCDIC table.
  740.  ATTRIBUTE           Determine A-packet generation.
  741.  BLOCK-CHECK         Level of error checking for file transfer.
  742.  CONTROLLER          Indicate type of terminal connection.
  743.  DEBUG               Log packet traffic during file transfer.
  744.  DELAY               Length of pause before a SEND subcommand.
  745.  EOF                 Text file truncation at CTRL-Z.
  746.  ETOA                Modify the Kermit-370 EBCDIC-to-ASCII table.
  747.  FILE                Attributes for incoming or outgoing files...
  748.    CHARACTER-SET     ... for 370 storage.
  749.    COLLISION         ... treatment for duplicate names.
  750.    LONGLINE          ... treatment of too-long records.
  751.    OVERWRITE         ... treatment of attributes.
  752.    TYPE              ... text or binary.
  753.    other             ... system-specific attributes.
  754.  FOREIGN             Strings added to outgoing filespec...
  755.    PREFIX
  756.    SUFFIX
  757.  INCOMPLETE          Determine the action on an aborted file transfer.
  758.  LINE                Specify alternate communication line.
  759.  MARGIN              for sending files...
  760. 11.4. Kermit-370 Subcommands                                             Page 15
  761. 0-------------------------------------------------------------------------------
  762.    LEFT
  763.    RIGHT
  764.  PROMPT              For Kermit-370 subcommands.
  765.  RETRY               Maximum retry count...
  766.    INIT              ... for initial packet exchange.
  767.    PACKET            ... per packet for ongoing transfer.
  768.  SERVER-TIMEOUT      Spacing between server NAK's.
  769.  SPEED               Line speed for packet-size calculations.
  770.  SYSCMD              Try apparently invalid Kermit subcommands on host system.
  771.  TABS-EXPAND         Determine tab-to-space conversion on reception.
  772.  TAKE
  773.    ECHO              Echo subcommands read from TAKE files.
  774.    ERROR-ACTION      Exit from TAKE file on command error.
  775.  TEST                Facilitate testing of Kermit.
  776.  TATOE               Modify the Kermit-370 ASCII-to-EBCDIC table.
  777.  TETOA               Modify the Kermit-370 EBCDIC-to-ASCII table.
  778.  TRANSFER            Options...
  779.    CHARACTER-SET     ... for transmission.
  780.  TTABLE              Determine which tables undo the terminal translation.
  781.  8-BIT-QUOTE         Determine state of 8th-bit prefixing.
  782.  SEND or RECEIVE
  783.    END-OF-LINE       Packet terminator.
  784.    PACKET-SIZE       Maximum packet size.
  785.    PAD-CHAR          Character to insert before each packet.
  786.    PADDING           Number of pad characters to insert.
  787.    PARITY            Indicate if 7-bit or 8-bit data.
  788.    QUOTE             Use to quote control characters in packets.
  789.    START-OF-PACKET   Packet beginning marker.
  790.    TIMEOUT           Time limit for response.
  791. 0
  792.  SET ATOE etc.
  793. 0Syntax: SET table [num1 num2]
  794. 0This  modifies  one  of  the ASCII/EBCDIC translation tables used by Kermit-370
  795.  (for example, to conform to your system).  The  valid  table  names  are  ATOE,
  796.  ETOA, TATOE, and TETOA.  The arguments are, respectively, the offset within the
  797.  named table and the new value for that offset.  If the arguments  are  omitted,
  798.  the table is restored to its initial arrangement.  Both num1 and num2 should be
  799.  in the range 0-255 (decimal).  For example, in ATOE or TATOE, the offset is the
  800.  ASCII  character  code,  and  the new value is the new EBCDIC result code.  In-
  801.  itially, ATOE and TATOE each contain two identical copies of  the  7-bit  ASCII
  802.  character  table.    Helpful  hint: if you have files that make use of extended
  803.  (8-bit) ASCII codes and wish to upload them via Kermit-370, be sure  to  define
  804.  unique  EBCDIC  equivalents  of  all the needed 8-bit ASCII codes or else treat
  805.  such files as binary data.  Any time you use the SET ATOE or SET  ETOA  subcom-
  806.  mands,  that has a side effect equivalent to SET ATTRIBUTE ENCODING OFF (q.v.).
  807.  If the extended ASCII character set is one of those supported for file transfer
  808.  in Kermit-370, you need only issue a SET TRANSFER CHARACTER-SET (q.v.).
  809. 0Note:  the  meaning of the tables depends on the TTABLE setting -- if TTABLE is
  810.  OFF, the TATOE and TETOA tables are not used.
  811. 11.4. Kermit-370 Subcommands                                             Page 16
  812. 0-------------------------------------------------------------------------------
  813.  SET ATTRIBUTE
  814. 0Syntax: SET ATTRIBUTE [attribute] ON or OFF
  815. 0The individual attributes are  LENGTH,  TYPE,  DATE,  CREATOR,  ACCOUNT,  AREA,
  816.  PASSWORD,  BLOCKSIZE,  ACCESS,  ENCODING, DISPOSITION, PROTECT, ORIGIN, FORMAT,
  817.  SYS-INFO, and BYTE-LENGTH.  Kermit-370 distinguishes between the two  forms  of
  818.  this subcommand by counting "words".  In order to see the list of supported at-
  819.  tributes, you must enter "SET ATTR ? ?"; if you enter just "SET ATTR ?", Kermit
  820.  will list just the alternatives ON and OFF.
  821. 0ON      The  specified  attribute  is to be processed, or attribute packets are
  822.          generated for all outgoing files, provided the other  Kermit  indicates
  823.          the ability to accept them.  (Default).
  824. 0OFF     The  specified  attribute  is  to  be ignored and not generated, or at-
  825.          tribute packets are never generated.
  826. 0
  827.  SET BLOCK-CHECK
  828. 0Syntax: SET BLOCK-CHECK number
  829. 0This determines the type of block check used during file transfer, provided the
  830.  other  Kermit  agrees.    Valid  options for number are: 1 (for a one-character
  831.  checksum), 2 (for a two-character checksum) and 3 (for a three-character  CRC).
  832.  This  is one of only two Send-Init parameters that cannot be SET separately for
  833.  SEND and RECEIVE.
  834. 0
  835.  SET CONTROLLER
  836. 0Syntax: SET CONTROLLER type
  837. 0The type may be TTY, SERIES1, GRAPHICS,  AEA,  FULLSCREEN,  VTAMTTY,  or  NONE.
  838.  Kermit-370  automatically  determines  whether you are connected via a Series/1
  839.  (or similar) emulation controller or a TTY line.  In some  circumstances,  such
  840.  as when the connection is through a non-graphics-capable 3174 port, Kermit will
  841.  set CONTROLLER to NONE, which has the effect of disabling file transfers.  This
  842.  subcommand is provided, though, to allow the automatic choice to be superseded,
  843.  and because Kermit may not be able to  distinguish  between  Series/1-type  and
  844.  other  3270-emulation  controllers.   In particular, there is no way to distin-
  845.  guish between FULLSCREEN and GRAPHICS from within Kermit.  When  CONTROLLER  is
  846.  set  to SERIES1, GRAPHICS, or AEA, Kermit disables the 3270 protocol conversion
  847.  function by putting the terminal controller into "transparent mode", which  al-
  848.  lows Kermit packets to pass through intact.  Note: an incorrect CONTROLLER set-
  849.  ting may lock up or wipe out your session when you try to transfer files.
  850. 0Kermit operation is possible through an IBM 3708  front  end,  but  only  in  a
  851.  rather  specific configuration.  See the installation guide for your variant of
  852.  Kermit-370 for the details of that and other hardware-related restrictions  and
  853.  configurations.
  854. 11.4. Kermit-370 Subcommands                                             Page 17
  855. 0-------------------------------------------------------------------------------
  856.  SET DEBUG
  857. 0Syntax: SET DEBUG OFF or ON [RAW] [I/O] [SAVE] [LONG]
  858. 0Note:  any  combination,  in  any  order,  of  RAW, I/O, and SAVE may follow or
  859.  replace ON.  Each of the three implies ON.
  860. 0ON      Keep a journal of all packets sent and received in a log file on  disk.
  861.          If the file already exists, it is erased and overwritten.  The filespec
  862.          of the log is, of course, system-dependent.  All packets are logged  in
  863.          EBCDIC  for  legibility,  even  when  CONTROLLER  is  set  to  SERIES1,
  864.          GRAPHICS, or AEA.
  865. 0RAW     The same as ON, but packets are logged in the form that is passed to or
  866.          from  the  operating system, i.e., EBCDIC for TTY or VTAMTTY terminals,
  867.          and ASCII for SERIES1, GRAPHICS, and AEA terminals.
  868. 0I/O     The same as ON, but the log includes additional transmission status in-
  869.          formation, such as the AID returned by a full-screen device.  See below
  870.          for a summary of the log formats.
  871. 0SAVE    The same as ON, but the log file is closed after each entry  is  added,
  872.          so  that, if the session is abnormally terminated, the log file will be
  873.          complete and readable.
  874. 0LONG    The same as I/O, but the additional information is not truncated to  36
  875.          bytes.
  876. 0OFF     Stop logging packets and close the the log file.  (Default.)
  877. 0Often,  problems  with  Kermit  file transfers or server-mode operations can be
  878.  diagnosed by setting DEBUG on in one or both Kermits, regardless of  where  the
  879.  problems  actually  lie.  For Kermit-370, the maximum amount of information can
  880.  generally be obtained by setting DEBUG to I/O or LONG, but the  format  of  the
  881.  log  depends  somewhat  on which variant of Kermit-370 is involved.  Before ex-
  882.  amining the log, you should set DEBUG OFF either explicitly or by exiting  from
  883.  Kermit-370.
  884. 0There  is  an  optional feature for logging dumps of storage blocks at selected
  885.  points in the execution.  By default, this feature  is  disabled  (at  assembly
  886.  time) by having the variable symbol &KTRACE set to NO and also by virtue of the
  887.  fact that no calls to the dump routine are present in  the  distribution  code.
  888.  Further, the dumps are suppressed unless both DEBUG and TEST (q.v.) are set on.
  889.  To select when and what blocks to dump, it is  necessary  to  insert  calls  to
  890.  KHDMP  at  appropriate  points in the source before assembling.  Each such call
  891.  generates a dump each time it is executed, provided that  DEBUG  and  TEST  are
  892.  set,  and  the contents of all registers are preserved.  The call specifies the
  893.  starting address, the length, and a short title for  the  block.    Only  eight
  894.  characters of the title will be used.  Some examples:
  895. 0            KHDMP ATOE+128,128,'ATOEhigh'
  896.                            Dump the 2nd half of the ATOE table.
  897. 0            KHDMP KHDSAV,20,'R14 - R2'
  898.                            Dump registers 14-2.
  899. 0            KHDMP 32(,13),40,'**R3-R12'
  900. 11.4. Kermit-370 Subcommands                                             Page 18
  901. 0-------------------------------------------------------------------------------
  902.                            Dump registers 3-12.
  903. 0            KHDMP (3),(0),'**QBLOCK'
  904.                            Dump  block  addressed by R3 with length specified in
  905.                            R0.
  906. 0There is another debugging facility that is  enabled  by  the  variable  symbol
  907.  &KTRACE  along  with  the  dump option, namely, an execution trace.  There is a
  908.  circular buffer of trace elements in Kermit's working storage, and a  new  ele-
  909.  ment  is  written each time a Kermit subroutine is called or returns.  The ele-
  910.  ments contain the subroutine name plus (on entry) a  sequence  number  and  the
  911.  contents  of  registers 0 and 1 or (on exit) the character ">" and the contents
  912.  of registers 15 and 1.  There is also a mechanism for tracing extra  events  by
  913.  inserting KTRACE calls into the source.  For example,
  914. 0            KTRACE 0(5),REGS=5
  915.                            Trace eight bytes pointed to by R5 and R5 itself.
  916. 0            KTRACE FOOBAR Trace eight bytes at label FOOBAR.
  917. 0            KTRACE 'Found it',REGS=(1,7)
  918.                            Trace 'Found it', R1, and R7.
  919. 0The  trace  table is simply updated in storage, eating its own tail.  It can be
  920.  found in a memory dump by locating the "eye-catcher" that says "KTRACE:", which
  921.  precedes the start, current, and end pointers for the table.  Usually, there is
  922.  no access to the table except in ABEND dumps and the like.   It  would  not  be
  923.  very  useful  to have a KHDMP call for the table, since each line dumped to the
  924.  debug log would cause at least four other lines in the table to be  overwritten
  925.  by the ongoing trace, thereby losing most of the desired information.
  926. 0Each  line  in  the debug log begins with a one-letter tag and a colon and con-
  927.  tains information according to the tag.  The following tags are defined.
  928. 0S:  The text of a packet sent.  Normally, it will be encoded in EBCDIC for con-
  929.      venience,  but  if  DEBUG  is set to RAW, the packet will appear exactly as
  930.      passed to or from the system, i.e., in EBCDIC for TTY or VTAMTTY lines  and
  931.      in ASCII for full-screen lines.
  932. 0R:  The text of a packet received.  The same encoding applies.
  933. 0A:  The  AID  and  buffer address returned by a full-screen device along with a
  934.      read operation (three characters in all).  The values should all be  print-
  935.      able  EBCDIC.   This obsolete tag was used by TSO and MUSIC Kermits and ap-
  936.      peared only when DEBUG was set to I/O.
  937. 0*:  Data dumped by the optional KHDMP routine.
  938. 0The following tags appear only when DEBUG is set to I/O or LONG.    All  values
  939.  are  in  hexadecimal.   The meanings differ slightly according to the operating
  940.  system.  For CMS, the I/O parameter list is a channel command; for TSO or  ROS-
  941.  COE,  the  SVC  93  (TPUT/TGET)  parameters;  for  CICS, an intermediate string
  942.  similar to channel commands.  Similarly, the status data consist of the  stored
  943.  CSW plus an attention interrupt indicator for CMS, but the return code from the
  944.  I/O operation for TSO, ROSCOE, CICS, and MUSIC.
  945. 11.4. Kermit-370 Subcommands                                             Page 19
  946. 0-------------------------------------------------------------------------------
  947.  a:  Channel and device status after an unexpected attention interrupt.
  948. 0b:  I/O parameter list for recovering from a CP break-in on screen.
  949. 0c:  I/O parameter list for resuming normal screen operation.
  950. 0d:  Data transferred on the previously indicated I/O operation.
  951. 0e:  Status data after an I/O command has completed with an error.
  952. 0g:  I/O parameter list for reading from the screen buffer.
  953. 0i:  Status data after an I/O command has completed normally.
  954. 0m:  I/O parameter list for displaying text on the screen.
  955. 0o:  I/O parameter list for initializing the screen for transfers.
  956. 0r:  I/O parameter list for reading from the terminal.
  957. 0w:  I/O parameter list for a transparent write.
  958. 0?:  I/O parameter list for some other operation, such as clearing the screen.
  959. 0
  960.  SET DELAY
  961. 0Syntax: SET DELAY number
  962. 0Normally, Kermit-370 waits 10 seconds after the SEND subcommand before starting
  963.  the  transfer,  but this delay may be set to any non-negative value.  Two DELAY
  964.  values have special meaning.  When DELAY is 1, the usual two-line greeting dis-
  965.  played during protocol mode is abbreviated to a short message (the default Ker-
  966.  mit prompt with three dots...), and when DELAY is 0, the greeting is suppressed
  967.  entirely,  along  with the extra one-second pause for subcommands like RECEIVE,
  968.  SERVER, REMOTE, and the like.
  969. 0
  970.  SET EOF
  971. 0Syntax: SET EOF ON or OFF
  972. 0ON      Scan each incoming TEXT file for the first occurrence of CTRL-Z and ig-
  973.          nore  the remainder of the file (but continue decoding up to the actual
  974.          end of the file).  BINARY files are not affected.
  975. 0OFF     Accept incoming files in their entirety.  (Default.)
  976. 0
  977.  SET FILE CHARACTER-SET
  978. 0Syntax: SET FILE CHARACTER-SET name
  979. 0Specifies the name of the character set used in files stored  on  disk.    This
  980.  setting  may  be  superseded  by an Attribute packet of an incoming file.  Cur-
  981.  rently, the available names are  CP037,  CP273,  CP275,  CP277,  CP278,  CP280,
  982. 11.4. Kermit-370 Subcommands                                             Page 20
  983. 0-------------------------------------------------------------------------------
  984.  CP281,  CP282,  CP284,  CP285, CP290, CP297, CP424, CP500, CP838, CP870, CP871,
  985.  CP875,  CP880,  CP905,  CZECH,  DKOI,  EBCDIC,  H-EBCDIK-DASH,  and  KANJI  (or
  986.  FUJITSU-KANJI, HITACHI-KANJI, or IBM-KANJI).  The names beginning with CP refer
  987.  to IBM code pages, while DKOI is the Cyrillic standard GOST  19768-87  used  in
  988.  the USSR, CZECH is a character set sometimes used in Czechoslovakia, and EBCDIC
  989.  (the default) is the traditional de facto standard EBCDIC  character  set.    A
  990.  character  set other than the default may be required by local conventions and,
  991.  if so, should be specified in the system or user INIT files.  See Table 1-1 for
  992.  the  allowed combinations of transfer and file character sets.  Explicitly set-
  993.  ting this option has a side effect equivalent to issuing SET ATTRIBUTE ENCODING
  994.  ON (q.v.).
  995. 0The  name  KANJI  is actually just an alias for the local preferred proprietary
  996.  Kanji code (Fujitsu, Hitachi, or IBM).  The various Kanji character  sets  have
  997.  two-byte  codes  (DBCS),  but are used with one-byte code pages (SBCS) as well.
  998.  It is normally necessary to issue two SET FILE CHARACTER-SET SUBCOMMANDS in or-
  999.  der  to  set  up  for  a DBCS: first, selecting a compatible SBCS, and, second,
  1000.  selecting the DBCS itself.  If  the  current  SBCS  is  incompatible  with  the
  1001.  selected  DBCS,  a default will be chosen.  This default, along with the choice
  1002.  of the particular proprietary character set associated with the alias KANJI, is
  1003.  chosen by the installer.
  1004. 0
  1005.  SET FILE COLLISION
  1006. 0Syntax: SET FILE COLLISION action
  1007. 0Specifies  the action to take when an incoming file has the same name as an ex-
  1008.  isting one.  Two of the options involve choosing an  alternative,  unique  name
  1009.  similar   to   the   one   in   conflict,  but  the  details  of  choosing  are
  1010.  system-specific.  Typically, the method involves adding digits to the  existing
  1011.  name.
  1012. 0APPEND       The  new file is appended to the old one.  This option has the the
  1013.               same effect as the old subcommand SET APPEND ON.
  1014. 0BACKUP       The existing file is renamed,  and  the  new  file  is  given  the
  1015.               desired name as if no conflict had occurred.
  1016. 0DISCARD      The incoming file is rejected by returning a "cancel file" indica-
  1017.               tion on any Data packets.
  1018. 0OVERWRITE    The existing file is overwritten with the incoming file.  This  is
  1019.               the  default for the CMS, TSO, ROSCOE, and MUSIC variants.  Chang-
  1020.               ing this default is a good candidate for INIT files.    When  COL-
  1021.               LISION  is  set  to  OVERWRITE, the attributes of the new file are
  1022.               determined by the current setting of FILE OVERWRITE (q.v.).
  1023. 0RENAME       The incoming file is renamed so as not to destroy (overwrite)  the
  1024.               pre-existing one, and the new name is returned to the sending Ker-
  1025.               mit for information purposes.  This has the same effect as the old
  1026.               subcommand  SET  WARNING  ON.    This  is the default for the CICS
  1027.               variant.
  1028. 11.4. Kermit-370 Subcommands                                             Page 21
  1029. 0-------------------------------------------------------------------------------
  1030.  SET FILE LONGLINE
  1031. 0Syntax: SET FILE LONGLINE FOLD or TRUNCATE or HALT
  1032. 0This specifies the action to take when a received line is longer than the  cur-
  1033.  rent  maximum  record  length.    That length is determined by the context in a
  1034.  system-specific way.  Refer to the description of the RECEIVE subcommand in the
  1035.  appropriate chapter for details.
  1036. 0FOLD       Specifies  that  long lines are to be split into two or more records
  1037.             as needed, all but the last being of the maximum length.    No  null
  1038.             records  are  created when the received line is an exact multiple of
  1039.             the record length.  BINARY files are,  by  definition,  always  con-
  1040.             sidered  as a single line and, therefore, are always folded, regard-
  1041.             less of the setting of this parameter.  V-BINARY and D-BINARY files,
  1042.             on the other hand, are reconstructed by folding at points determined
  1043.             by the context within the received file, and cannot be  folded  fur-
  1044.             ther  to  fit the current maximum length.  Any such records that are
  1045.             too long will be truncated.
  1046. 0TRUNCATE   Specifies that long lines are to be truncated at the maximum length.
  1047.             (Default.)   Kermit-370 takes note of the number of such truncations
  1048.             performed on a file and reports it in the STATUS  message  and  also
  1049.             treats  the fact of truncation as an error when the file transfer is
  1050.             complete.  The file will have been transferred,  but  obviously  not
  1051.             quite  intact.    However, this option can be useful for some tasks,
  1052.             such as stripping sequence numbers from card images.  The process is
  1053.             similar  to  that  provided  by  the SET MARGIN RIGHT subcommand for
  1054.             sending files.
  1055. 0HALT       Specifies that a file transfer is to halt immediately if a  received
  1056.             line  is too long.  Kermit-370 then issues an error packet and stops
  1057.             the transfer.
  1058. 0
  1059.  SET FILE OVERWRITE
  1060. 0Syntax: SET FILE OVERWRITE DEFAULT or PRESERVE
  1061. 0DEFAULT    Specifies that the current file attribute settings are  to  be  used
  1062.             for  the  new  file.    The result is roughly the same as if the old
  1063.             file, if  any,  were  completely  erased  before  the  new  file  is
  1064.             received.  (Default.)
  1065. 0PRESERVE   Specifies  that  the attributes of the file being overwritten are to
  1066.             be retained and used for the new file.  The result  is  roughly  the
  1067.             same  as  if  the  old files contents were deleted, and the new file
  1068.             were appended to the empty stub.
  1069. 0
  1070.  SET FILE TYPE
  1071. 0Syntax: SET FILE TYPE type
  1072. 0Specifies the type of data comprising files to be sent or received.  This  set-
  1073.  ting  may  be  temporarily superseded by the Attribute packets for a file being
  1074. 11.4. Kermit-370 Subcommands                                             Page 22
  1075. 0-------------------------------------------------------------------------------
  1076.  received.
  1077. 0TEXT       Specifies ordinary text.  ASCII-to-EBCDIC or EBCDIC-to-ASCII  trans-
  1078.             lation  is  performed on the data.  Trailing blanks are removed, and
  1079.             CRLF's are appended to outgoing records. CRLF's are used,  in  turn,
  1080.             to  determine  the  end  of  incoming records, which are padded with
  1081.             blanks if necessary to fill buffers.   (Default.)    Note:  trailing
  1082.             blanks  are  removed  from  outgoing, varying-length records only if
  1083.             they consist of a single blank each, or if there is a  right  margin
  1084.             specified  (q.v.).    Further  note:  a  given file is intrinsically
  1085.             categorized as fixed-length or varying-length (or  undefined-length)
  1086.             by  the file system and cannot be changed simply by setting the FILE
  1087.             RECFM  parameter  in  Kermit.    Conversion  between  formats  is  a
  1088.             system-specific  function;  see  the system documentation or consult
  1089.             your local support staff for details on conversion techniques.
  1090. 0BINARY     Specifies bit-stream data.  No translation is performed,  no  CRLF's
  1091.             are  added  to  outgoing  records,  and blanks are neither added nor
  1092.             removed.  Incoming bytes  are  added  successively  to  the  current
  1093.             record  buffer,  which  is  written  out  when  the current LRECL is
  1094.             reached.  Padding, if necessary, is done with nulls.
  1095. 0V-BINARY   Specifies varying-length-record binary data.  This type is like  BI-
  1096.             NARY, except that a two-byte binary prefix is added to each outgoing
  1097.             record giving the number of data bytes, and incoming records are set
  1098.             off by (and stripped of) their prefixes on receipt.
  1099. 0D-BINARY   Is  like  V-BINARY  except  that  the  length prefixes are five-byte
  1100.             ASCII-encoded decimal (right-justified with leading zeroes).
  1101. 0
  1102.  SET FOREIGN
  1103. 0Syntax: SET FOREIGN PREFIX string
  1104. 0This defines a prefix string to be added to the outgoing filespec generated  by
  1105.  the  SEND  subcommand.  For example, the string might be set to "B:" to specify
  1106.  output to the B disk drive on the other Kermit's system.  The default is a null
  1107.  string.  There is also a FOREIGN SUFFIX handled in the same manner.
  1108. 0
  1109.  SET HANDSHAKE
  1110. 0Syntax: SET HANDSHAKE number
  1111. 0This defines the character, if any, that Kermit-370 should send (or cause to be
  1112.  sent) immediately before reading each packet.  The character is  given  as  the
  1113.  decimal  of  an  ASCII  control  character, or as zero if no handshake is to be
  1114.  sent.  The default is 17 (XON), and any value in the range 0-31 is  valid,  but
  1115.  13 (CR) should not be used because it is generally the end-of-packet character.
  1116.  When Kermit-370  is  running  through  a  full-duplex  connection  (such  as  a
  1117.  "SERIES1"),  the  traditional  IBM  handshaking is not necessary, and HANDSHAKE
  1118.  should be set to 0 (as long as the other Kermit can be instructed not to expect
  1119.  a  handshake).  Note the distinction between SET HANDSHAKE in Kermit-370 (where
  1120.  it defines a character to be sent) and in many micro Kermits (where it  defines
  1121.  a character to be expected).
  1122. 11.4. Kermit-370 Subcommands                                             Page 23
  1123. 0-------------------------------------------------------------------------------
  1124.  SET INCOMPLETE
  1125. 0Syntax: SET INCOMPLETE DISCARD or KEEP
  1126. 0DISCARD   Specifies that incomplete files (that is, files partially received in
  1127.            a transfer cancelled by the other Kermit) are to be erased.  This  is
  1128.            the  default.    Note  that when FILE COLLISION is APPEND, incomplete
  1129.            files are never erased, lest pre-existing data be lost.
  1130. 0KEEP      Specifies that incomplete files are to be kept.
  1131. 0
  1132.  SET LINE
  1133. 0Syntax: SET LINE [name]
  1134. 0This specifies an alternate communication line for file transfers.  If the name
  1135.  is omitted, the default line (the user's terminal) is used.  The format of name
  1136.  is, of course, system-dependent, and some variants of Kermit-370 do not support
  1137.  any alternate lines.  No variant currently allows Kermit-370 to CONNECT over an
  1138.  alternate line.
  1139. 0
  1140.  SET MARGIN
  1141. 0Syntax: SET MARGIN side column
  1142. 0When Kermit-370 sends a text file, each line may be truncated on  the  left  or
  1143.  right (or both) at fixed column numbers.  Only the text from the left margin to
  1144.  the right margin (inclusive) will be sent, and any trailing blanks in the trun-
  1145.  cated lines will be stripped.  A value of zero for either margin disables trun-
  1146.  cation on that side.
  1147. 0
  1148.  SET PROMPT
  1149. 0Syntax: SET PROMPT [string]
  1150. 0This defines the character string that Kermit-370 displays when  asking  for  a
  1151.  subcommand.   The prompt may be any string of up to 20 characters.  The default
  1152.  is the name of the system-specific variant of  Kermit-370  followed  by  a  ">"
  1153.  sign,  e.g.,  Kermit-CMS>.    If the string is omitted, normal system prompting
  1154.  will occur.
  1155. 0
  1156.  SET RETRY
  1157. 0Syntax: SET RETRY INITIAL or PACKETS number
  1158. 0Kermit-370 resends its last packet after receiving a NAK or bad packet, but  it
  1159.  eventually  gives  up after repeated failures on the same packet.  The limit on
  1160.  retries can be set separately for the initial  packet  exchange  (Send-Init  or
  1161.  server-mode  command)  and for ordinary packets.  The default for INITIAL is 16
  1162.  and for PACKETS, 5.  Either limit can be set to any positive value.
  1163. 11.4. Kermit-370 Subcommands                                             Page 24
  1164. 0-------------------------------------------------------------------------------
  1165.  SET SERVER-TIMEOUT
  1166. 0Syntax: SET SERVER-TIMEOUT time
  1167. 0This defines the time in seconds that Kermit-370 in server mode should wait for
  1168.  a command before sending a NAK packet.  The default is 120.  A value of 0 means
  1169.  that Kermit should wait indefinitely, not only in the server loop, but  in  all
  1170.  transfers, regardless of the timeout value specified by the other Kermit.  Some
  1171.  variants are unable to time out in any  case.    Also,  timeouts  are  not  im-
  1172.  plemented for any of the full-screen terminal controllers.
  1173. 0
  1174.  SET SPEED
  1175. 0Syntax: SET SPEED number
  1176. 0This determines the communication line speed assumed by Kermit-370 in calculat-
  1177.  ing the optimum packet size.  If the value is zero, such calculations are  sup-
  1178.  pressed.    This  option is purely informative and has no effect on actual line
  1179.  speed.  (Default 1200.)
  1180. 0
  1181.  SET SYSCMD
  1182. 0Syntax: SET SYSCMD ON or OFF
  1183. 0ON      If the user enters a command string which is not a valid Kermit subcom-
  1184.          mand,  Kermit-370 will pass the string along to the host operating sys-
  1185.          tem for execution.  If the string is rejected by the  system  as  well,
  1186.          Kermit will report it as an invalid Kermit subcommand.  Otherwise, Ker-
  1187.          mit will assume the string was intended as  a  host  command  and  will
  1188.          simply report the completion code if non-zero.
  1189. 0OFF     Invalid  Kermit  subcommands  are simply rejected as such.  System com-
  1190.          mands may be executed, of course, but only by  specifying  the  generic
  1191.          prefix "HOST" or the appropriate system-specific prefix, such as CMS or
  1192.          TSO.  (Default.)
  1193. 0
  1194.  SET TABS-EXPAND
  1195. 0Syntax: SET TABS-EXPAND ON [list] or OFF
  1196. 0ON      Tab characters in incoming TEXT files  are  replaced  by  one  or  more
  1197.          blanks to bring the record size up to the next higher multiple of eight
  1198.          for each tab.  If tab settings other than columns 1, 9,  17,  etc.  are
  1199.          desired,  they  may  be  specified  explicitly  in a list following the
  1200.          keyword "ON".  Items in the list may be separated by spaces  or  commas
  1201.          and must be in strictly increasing order.
  1202. 0OFF     Incoming tabs are retained.  (Default.)
  1203. 11.4. Kermit-370 Subcommands                                             Page 25
  1204. 0-------------------------------------------------------------------------------
  1205.  SET TAKE ECHO
  1206. 0Syntax: SET TAKE ECHO ON or OFF
  1207. 0ON      Subcommands are echoed to the terminal as they are executed from a TAKE
  1208.          file.
  1209. 0OFF     Subcommands from a TAKE file are executed "silently."  (Default.)
  1210. 0
  1211.  SET TAKE ERROR-ACTION
  1212. 0Syntax: SET TAKE ERROR-ACTION CONTINUE or HALT
  1213. 0CONTINUE   Execution continues in a TAKE file regardless of  illegal  commands,
  1214.             except in server mode.  (This is the default.)
  1215. 0HALT       A  command error in a TAKE file causes immediate exit to Kermit sub-
  1216.             command level.
  1217. 0
  1218.  SET TEST
  1219. 0Syntax: SET TEST ON or OFF
  1220. 0ON      Allow setting the START-OF-PACKET and other special characters  to  any
  1221.          value, and suppress type 1 checksum testing on received packets.
  1222. 0OFF     Normal operation.  (Default.)
  1223. 0
  1224.  SET TRANSFER CHARACTER-SET
  1225. 0Syntax: SET TRANSFER CHARACTER-SET name
  1226. 0Specifies  the  name  of  the character set used in sending or receiving files.
  1227.  This setting may be superseded by an Attribute  packet  of  an  incoming  file.
  1228.  Currently,  the  available  names  are  ASCII  (the  default), CYRILLIC, GREEK,
  1229.  HEBREW, JAPAN-EUC, KATAKANA, LATIN1, LATIN2,  LATIN3,  THAI,  and  TRANSPARENT.
  1230.  There  are  also  special aliases L1, L2, and L3 for the LATINx names.  All but
  1231.  JAPAN-EUC, TRANSPARENT, and ASCII represent 8-bit codes composed of a  pair  of
  1232.  94- or 96-character sets from the ISO registry combined with normal definitions
  1233.  for the so-called C0 and C1 characters.  JAPAN-EUC is a DBCS for encoding Kanji
  1234.  characters,  plus Roman, Greek, and Cyrillic.  ASCII is the traditional charac-
  1235.  ter set supported by Kermit,  but  one  of  the  newer,  8-bit  sets  would  be
  1236.  preferable  for  most  users.   This option is, therefore, a good candidate for
  1237.  inclusion in the system INIT file.  See Table 1-1 for the allowed  combinations
  1238.  of transfer and file character sets.  Explicitly setting this option has a side
  1239.  effect equivalent to issuing SET ATTRIBUTE ENCODING ON (q.v.).   There  is  one
  1240.  exception,  namely,  TRANSPARENT,  which  sets  ENCODING  OFF and replaces both
  1241.  translation tables with null operations, regardless of the current nominal file
  1242.  character set.
  1243. 0The  biggest  drawback of the built-in tables for the various character sets is
  1244.  that neither the ISO registry nor  IBM  defines  any  mapping  between  the  C1
  1245.  characters  (hex  80-9F  in ISO arrangements) and the characters of EBCDIC code
  1246. 11.4. Kermit-370 Subcommands                                             Page 26
  1247. 0-------------------------------------------------------------------------------
  1248.  pages.  Thus, the mappings in Kermit-370 tables are somewhat arbitrary, and fu-
  1249.  ture pronouncements may suddenly invalidate some or all of those 32 mappings.
  1250. 0
  1251.  SET TRANSFER LOCKING-SHIFT
  1252. 0Syntax: SET TRANSFER LOCKING-SHIFT ON or OFF or FORCED
  1253. 0ON      The Kermit locking-shift protocol is to be used in transfers to or from
  1254.          cooperating partners, provided that 8th-bit quoting is enabled.
  1255. 0OFF     The Kermit locking-shift protocol is not to be used.
  1256. 0FORCED  The Kermit locking-shift protocol is to  be  used,  regardless  of  the
  1257.          cooperation  of  the  other Kermit.  The encoding uses only the locking
  1258.          shifts, to the exclusion of 8th-bit quoting.
  1259. 0
  1260.  SET TTABLE
  1261. 0Syntax: SET TTABLE ON or OFF or KP
  1262. 0ON      The translation that undoes the terminal controller's ASCII/EBCDIC con-
  1263.          version comes from the TATOE and TETOA tables, rather than the ATOE and
  1264.          ETOA tables (which are used only for translating disk files).  This op-
  1265.          tion  has  no  effect  when there is no translation built into the con-
  1266.          troller, i.e., with SERIES1, GRAPHICS, and AEA connections.
  1267. 0OFF     The ATOE and ETOA tables are used for all translations  by  Kermit-370.
  1268.          (Default.)
  1269. 0KP      Same  as  ON, but also establishes values in the TATOE and TETOA tables
  1270.          based on IBM's corporate standard  ASCII/EBCDIC  translation  (distinct
  1271.          from the internationally accepted de facto standard).
  1272. 0
  1273.  SET 8-BIT-QUOTE
  1274. 0Syntax: SET 8-BIT-QUOTE char or ON or OFF
  1275. 0This  controls  whether eighth-bit prefixing is done and can be used to specify
  1276.  the character to be used.  This is one of only two  Send-Init  parameters  that
  1277.  cannot be SET separately for SEND and RECEIVE.
  1278. 0char    Eighth-bit prefixing will be done using char, provided the other Kermit
  1279.          agrees.  The default value is an ampersand.
  1280. 0ON      Eighth-bit prefixing will be done, provided the other Kermit explicitly
  1281.          requests it (and specifies the character).
  1282. 0OFF     Eighth-bit prefixing will not be done.
  1283. 11.4. Kermit-370 Subcommands                                             Page 27
  1284. 0-------------------------------------------------------------------------------
  1285.  SET SEND/RECEIVE
  1286. 0The  following  parameters  can be set either as SEND or RECEIVE options.  As a
  1287.  rule, in each pair, one is the operational value, and  the  other  is  used  to
  1288.  change  the default for Send-Init packets received from the other Kermit and to
  1289.  set up parameter values as if the other Kermit had specified them on  the  pre-
  1290.  vious  exchange.    When both values are described, the operational one will be
  1291.  first.  For all parameters besides QUOTE, the operational value is the RECEIVE.
  1292.  After  a transfer, the operational values will be unchanged, but the others (as
  1293.  displayed by SHOW) will reflect the parameters specified by the  other  Kermit.
  1294.  The  underlying  defaults established by previous SET subcommands will still be
  1295.  in effect.  In the syntax descriptions, mode is SEND or RECEIVE.
  1296. 0
  1297.  END-OF-LINE
  1298. 0Syntax: SET mode END-OF-LINE number
  1299. 0RECEIVE should not be changed.
  1300. 0SEND may be needed to establish contact.  If the other system needs packets  to
  1301.  be terminated by anything other than carriage return, specify the decimal value
  1302.  of the desired ASCII character.  number must be in the  range  0-31  (decimal).
  1303.  The default is 13 (CR).
  1304. 0
  1305.  PACKET-SIZE
  1306. 0Syntax: SET mode PACKET-SIZE number
  1307. 0RECEIVE  defines  number as the maximum length for incoming packets.  The valid
  1308.  range is 26-9024, but 94 is the limit for normal short-packet  protocol.    The
  1309.  default  is 80.  Specifying a value greater than 94 is necessary and sufficient
  1310.  to enable the long-packet protocol for transfers to  Kermit-370  (provided  the
  1311.  other  Kermit is willing).  Kermit-370 will actually accept long packets in any
  1312.  case, but the protocol requires that the other  Kermit  not  send  them  unless
  1313.  Kermit-370  asks.   Raising this value from the default is a good candidate for
  1314.  inclusion in INIT files.  In practice,  the  packet  size  may  be  limited  by
  1315.  hardware  and programming considerations.  See the system-specific chapters for
  1316.  details.
  1317. 0SEND might be needed for  sending  files  to  a  minimal  Kermit  that  neither
  1318.  specifies  a  buffer  size in the Send-Init sequence nor can accept the default
  1319.  (80).  It may also be used to specify the packet size for a "raw" download  via
  1320.  the  XTYPE  subcommand.  This parameter has no other function and is completely
  1321.  irrelevant to long packets.   If  the  other  Kermit  asks  for  long  packets,
  1322.  Kermit-370 will always comply.
  1323. 0
  1324.  PAD-CHAR
  1325. 0Syntax: SET mode PAD-CHAR number
  1326. 0RECEIVE defines number as the character to be used by the other Kermit for pad-
  1327.  ding packets.  The character must be an ASCII control character (in  the  range
  1328.  0-31).  The default is 0 (NULL).  This option is seldom useful.
  1329. 11.4. Kermit-370 Subcommands                                             Page 28
  1330. 0-------------------------------------------------------------------------------
  1331.  SEND  may  be needed to establish contact if the other Kermit (or the transmis-
  1332.  sion line) needs padded packets.
  1333. 0
  1334.  PADDING
  1335. 0Syntax: SET mode PADDING number
  1336. 0RECEIVE defines the number of pad characters to be  used  for  padding  packets
  1337.  from  the other Kermit.  This number may be anywhere from 0 to 94.  The default
  1338.  is 0.  This option is seldom useful.
  1339. 0SEND may be needed to establish contact if the other Kermit (or  the  transmis-
  1340.  sion line) needs padded packets.
  1341. 0
  1342.  PARITY
  1343. 0Syntax: SET mode PARITY MARK or NONE
  1344. 0RECEIVE  specifies  the  parity  expected  in  the  transparent-mode ASCII data
  1345.  received by the mainframe from a full-screen device.  Such data will  typically
  1346.  have  either  all  Mark  parity (seven data bits with the eighth bit set) or no
  1347.  parity (eight data bits).  This is typically not the same as the parity used in
  1348.  communications  between  the  protocol  convertor and the terminal.  Kermit-370
  1349.  must know which kind of parity  to  expect  in  order  to  calculate  checksums
  1350.  properly.  Since Kermit-370 does not actually verify parity, the other possible
  1351.  variants (ODD, EVEN, and SPACE) are lumped together with MARK  parity  for  the
  1352.  purpose  of  this subcommand, which merely chooses between 7-bit and 8-bit data
  1353.  transfer.  The default is MARK.
  1354. 0SEND is also an operational value, specifying the parity to  be  used  in  con-
  1355.  structing  outgoing  data  packets on full-screen devices.  NONE is the default
  1356.  and is generally preferable, in that it permits binary  transfers  without  the
  1357.  need for eighth-bit prefixing, but MARK may be required in some configurations.
  1358. 0
  1359.  QUOTE
  1360. 0Syntax: SET mode QUOTE char
  1361. 0SEND indicates a printable character for prefixing (quoting) control characters
  1362.  and  other prefix characters.  The only good reason to change this would be for
  1363.  sending a file that contains many "#" characters (the normal control prefix) as
  1364.  data.    It  must  be  a  single  character  with  ASCII  value 33-62 or 96-126
  1365.  (decimal).
  1366. 0RECEIVE would be needed only for talking to  a  crippled  Kermit  that  uses  a
  1367.  non-standard quoting character, but does not admit it.
  1368. 11.4. Kermit-370 Subcommands                                             Page 29
  1369. 0-------------------------------------------------------------------------------
  1370.  START-OF-PACKET
  1371. 0Syntax: SET mode START-OF-PACKET number
  1372. 0RECEIVE  defines  number  as  the character to be expected to mark the start of
  1373.  packets from the other Kermit.  The character must be an ASCII control  charac-
  1374.  ter  (in the range 0-31).  The default is 1 (SOH).  This may need to be changed
  1375.  to establish contact.
  1376. 0SEND may also need to be changed to establish contact.  It  defines  number  as
  1377.  the character to be used to mark outgoing packets.
  1378. 0
  1379.  TIMEOUT
  1380. 0Syntax: SET mode TIMEOUT time
  1381. 0RECEIVE  defines the time in seconds the other Kermit is to wait for a response
  1382.  from Kermit-370 before resending a packet.  The default is 5.   A  value  of  0
  1383.  means the other Kermit should wait indefinitely.
  1384. 0SEND  may  be  needed to define the time in seconds Kermit-370 is to wait for a
  1385.  response from the other Kermit in the initial  packet  exchange,  although  the
  1386.  default  value  0  (indefinite wait) is probably satisfactory, especially since
  1387.  Kermit-370 in many cases cannot time out anyway.  Specifying a  non-zero  value
  1388.  will  prevent  the  other  Kermit from ever requesting infinite "patience" from
  1389.  Kermit-370.
  1390. 0
  1391.                                THE SHOW SUBCOMMAND
  1392. 0Syntax: SHOW [option]
  1393. 0The SHOW subcommand displays the values of all parameters that can  be  changed
  1394.  with  the  SET  subcommand, except ATOE, ETOA, TATOE, and TETOA (for those, see
  1395.  the TDUMP subcommand).  If specified, option can be a particular  parameter  or
  1396.  the  keyword  "ALL"  (the default).  Groups of parameters, such as SEND, can be
  1397.  displayed by requesting the group name, or  individual  sub-parameters  can  be
  1398.  displayed by specifying the complete name.  For example,
  1399. 0  SHOW RECEIVE EOL
  1400. 0will  display  the  decimal value of the packet terminator that Kermit-370 cur-
  1401.  rently expects, i.e., 13.  Similarly,
  1402. 0  SHOW FOREIGN
  1403. 0will display the character strings currently in use for prefix  and  suffix  on
  1404.  each  outgoing  filespec.    When "ALL" is specified or implied, all parameters
  1405.  other than the attribute switches are displayed.
  1406. 11.4. Kermit-370 Subcommands                                             Page 30
  1407. 0-------------------------------------------------------------------------------
  1408.                               THE STATUS SUBCOMMAND
  1409. 0Syntax: STATUS
  1410. 0This subcommand displays information about the previously executed  subcommand.
  1411.  The  response  will include either the appropriate error message or the message
  1412.  "No errors".  The initial status is "No file transfers yet".    If  the  status
  1413.  reflects  an  error  condition,  the name of the last file used (excluding TAKE
  1414.  files) will be displayed as well.  If the error was detected by the other  Ker-
  1415.  mit,  the  message  will be "Micro aborted" followed by the text from the Error
  1416.  packet.  Conversely, if Kermit-370 detected the error, the text of  the  status
  1417.  message  will  have constituted the error packet sent out.  In any case, if the
  1418.  last file transfer was cancelled (by virtue of an attribute mismatch or  manual
  1419.  intervention),  the  reason  for cancellation is displayed.  Also, if the error
  1420.  occurred in disk I/O, any available explanatory information is displayed.  Nor-
  1421.  mally,  the  error status is altered only when a transfer-initiating subcommand
  1422.  (SEND or RECEIVE) is executed, but there are several exceptions.  If an invalid
  1423.  subcommand  is entered, the status becomes "Kermit command error", and the next
  1424.  subcommand entered will reset the status.  Also, in server mode  every  subcom-
  1425.  mand  is  received  through a transfer from the other Kermit and may affect the
  1426.  status (except the STATUS subcommand itself, of course).
  1427. 0Other information is also included.  When Kermit-370 has been forced  to  trun-
  1428.  cate  one or more records in the last RECEIVE operation (because of the current
  1429.  maximum record length), the number of  records  truncated  is  reported.    The
  1430.  status  display also includes throughput statistics for the last transfer: num-
  1431.  ber of files sent, duration, number of packets, number of retries, and averages
  1432.  of  bytes/packet  and  bytes/second.   These last two quantities are calculated
  1433.  separately for bytes sent and received on  the  communication  line  (including
  1434.  padding,  if any), and the last quantity is also calculated on the basis of the
  1435.  number of bytes read from or written to disk.  Further, if retries were  neces-
  1436.  sary,  Kermit-370 computes the optimum packet size assuming the retries to have
  1437.  been due to sparse, Poisson-distributed bursts of noise.    This  is  the  same
  1438.  heuristic   optimum  that  Kermit-370  computes  and  uses  as  an  alternative
  1439.  packet-size limit when sending long packets.  If TEST is set  on,  Kermit  also
  1440.  reports the maximum size attained by its storage stack since execution began.
  1441. 0
  1442.                                THE STOP SUBCOMMAND
  1443. 0Syntax: STOP
  1444. 0This  is  not a subcommand in the usual sense.  Instead, it is a command string
  1445.  that can be entered on the communication line while Kermit-370 is  in  protocol
  1446.  mode  and will cause protocol mode to cease immediately.  This may be useful if
  1447.  the other Kermit has crashed.  The word "stop" may be entered in  either  upper
  1448.  or  lower  case,  but  it  must be the only character string in the "packet" in
  1449.  question.
  1450. 11.4. Kermit-370 Subcommands                                             Page 31
  1451. 0-------------------------------------------------------------------------------
  1452.                                THE TAKE SUBCOMMAND
  1453. 0Syntax: TAKE filespec
  1454. 0Execute Kermit subcommands from the specified file, usually called a TAKE file.
  1455.  The  TAKE  file  may in turn include TAKE subcommands, and the nesting may con-
  1456.  tinue to a depth of ten.  If  a  TAKE  file  includes  the  subcommand  SERVER,
  1457.  however,  the  nesting  count  is saved and starts over again in server mode in
  1458.  case the client Kermit should transmit a REMOTE KERMIT TAKE command.  The  user
  1459.  has  the option of seeing the subcommands echoed from the TAKE file as they are
  1460.  executed and also the option of automatically exiting from a TAKE file  on  er-
  1461.  ror.  See the subcommand SET TAKE for details.
  1462. 0
  1463.                               THE TDUMP SUBCOMMAND
  1464. 0Syntax: TDUMP table-name or NAMES
  1465. 0This displays the contents of table-name.  The same table can be modified using
  1466.  the SET subcommand.  The ATOE, ETOA, TATOE, and TETOA tables can  presently  be
  1467.  displayed  and  changed.    The NAMES table is the transaction log for the last
  1468.  transfer, consisting of the filespec of each file sent or received, along  with
  1469.  the size (in Kbytes) and any error messages.
  1470. 0
  1471.                          THE TYPE AND XTYPE SUBCOMMANDS
  1472. 0Syntax: [X]TYPE filespec
  1473. 0These  subcommands  display  the named file.  TYPE is effectively a synonym for
  1474.  (and allows the same options as) the host system command for  displaying  files
  1475.  at  the  terminal,  but  XTYPE performs a raw file transfer on the current com-
  1476.  munication line (which need not be the terminal) according to the current  CON-
  1477.  TROLLER  setting.   Thus, XTYPE uses transparent mode if CONTROLLER is SERIES1,
  1478.  GRAPHICS, or AEA.  Also, it sends the data in bursts no larger than the current
  1479.  SEND  PACKET-SIZE.    Since XTYPE is basically a modified SEND, the options al-
  1480.  lowed on the filespec for SEND are also allowed for XTYPE.
  1481. 0
  1482.  1.5. Before Connecting to the Mainframe
  1483. 0Several options must be set in the micro Kermit before connecting to an IBM 370
  1484.  system  as  a  line-mode  device.  You should set LOCAL-ECHO to ON (to indicate
  1485.  half-duplex).  This is the norm but not true in absolutely every case; if  each
  1486.  character  appears  twice  on  your  terminal  screen,  set  LOCAL-ECHO to OFF.
  1487.  FLOW-CONTROL should be set to NONE, and on some systems HANDSHAKE should be set
  1488.  to XON.  The parity should be set according to the system's specifications.  On
  1489.  some micro Kermits, all of the above is done in one step using the DO IBM macro
  1490.  (or SET IBM ON).  Set the baud rate to correspond to the line speed.
  1491. 0Connecting  through  a full-screen device also requires that certain options be
  1492.  set in the micro Kermit.   You  should  set  LOCAL-ECHO  to  OFF  (to  indicate
  1493.  full-duplex).   FLOW-CONTROL should be set to XON/XOFF, and HANDSHAKE should be
  1494.  set to OFF.  For many systems, the PARITY should be set to EVEN.  Set the  baud
  1495.  rate to correspond to the line speed.
  1496. 0One  exception  to these rules is the case where the micro Kermit is attempting
  1497. 11.5. Before Connecting to the Mainframe                                 Page 32
  1498. 0-------------------------------------------------------------------------------
  1499.  automated  file  transfer,  e.g.,  downloading  several  separate  files   from
  1500.  Kermit-370  running  in server mode.  In fact, under those circumstances, hand-
  1501.  shaking is necessary even with "SERIES1" connections, and the two Kermits  must
  1502.  be  instructed to adopt a common handshake character (e.g., by SET HANDSHAKE 10
  1503.  to Kermit-370 and SET HANDSHAKE LF to the micro).
  1504. 0In any case, you should make sure that either the micro  Kermit  or  Kermit-370
  1505.  will  provide  timeouts  during file transfers (if not both).  Some variants of
  1506.  Kermit-370 (notably CMS) cannot provide timeouts, and you may need to  set  the
  1507.  TIMER to ON in the micro.
  1508. 0When  you are connecting through a protocol convertor, it is useful to know the
  1509.  key sequence that causes the screen image to be repainted from the controller's
  1510.  memory.  In many cases, it is CTRL-V, although CTRL-G and CTRL-C are also some-
  1511.  times used.  In general, this sequence should be typed whenever reconnecting to
  1512.  Kermit-370  after being in Kermit protocol mode (and sometimes after merely es-
  1513.  caping to the local Kermit), since the  local  Kermit  may  have  modified  the
  1514.  screen.
  1515. 0
  1516.  1.6. Trouble-shooting Protocol Converters
  1517. 0Many,  but not all, protocol converters have transparent modes that permit Ker-
  1518.  mit file transfers.  The welter of competing and often incompatible  communica-
  1519.  tions  devices  would  cause  a major headache, except for three circumstances.
  1520.  First, Kermit-370 has routines for automatically detecting which kind of  front
  1521.  end  is  controlling  the  current session; second, the Kermit installer is en-
  1522.  couraged to tailor Kermit to force the correct choice  of  CONTROLLER  whenever
  1523.  those  routines  don't  work  properly; and, third, Kermit offers a last-resort
  1524.  mode of operation that will work with almost any protocol converter.    Because
  1525.  of  the  limitations  in  the  catch-all mode (known as FULLSCREEN mode), it is
  1526.  still best to take advantage of the transparency, if any, in the protocol  con-
  1527.  verter,  and the automatic detection routines still play an important role.  It
  1528.  will be instructive to outline what those routines actually do and how they can
  1529.  go wrong.
  1530. 0
  1531.  Recognizing a Series/1
  1532. 0Although  protocol  converters are advertised as simulating the behavior of IBM
  1533.  3270-type terminals, there generally are differences which  could  be  used  to
  1534.  distinguish  each  type  of device from the others and from real 3270-type ter-
  1535.  minals.  However, all that really matters to Kermit-370 is whether there  is  a
  1536.  transparent  mode  available  such  that file transfers can be carried out.  To
  1537.  date, only three fundamentally different transparent modes have  been  reported
  1538.  to  Columbia,  and  it seems likely that no others have been (or, perhaps, ever
  1539.  will be) implemented.  All are supported by Kermit.
  1540. 0Kermit-370 recognizes these front  ends  automatically  by  making  two  simple
  1541.  tests.    The  first  takes advantage of one of the advanced features first im-
  1542.  plemented in the Yale ASCII system and  subsequently  copied  in  many  of  the
  1543.  devices that adopted the same transparent mode.  This feature is a special 3270
  1544.  data-stream order which requests a status report from the  protocol  converter.
  1545.  Kermit  sends  this  order  and then reads the "3270 screen".  If Kermit sees a
  1546.  valid status report, it sets CONTROLLER to SERIES1 and stops testing.
  1547. 11.6. Trouble-shooting Protocol Converters                               Page 33
  1548. 0-------------------------------------------------------------------------------
  1549.  Two catches
  1550. 0Obviously, the Yale status order is not implemented  in  most  other  kinds  of
  1551.  hardware.  Thus, the order would be rejected by a non-Yale-type controller, and
  1552.  that could have undesirable side effects on the hardware.  However, hardware is
  1553.  generally  designed  to be robust -- the real drawback lies in the side effects
  1554.  on certain communications software (notably VTAM/TSO), which may respond  badly
  1555.  while  trying to protect the robust hardware from illegal orders.  If it proves
  1556.  impossible to make the external software behave properly, the only recourse  is
  1557.  to  modify  Kermit-370  to skip the first test altogether and possibly to force
  1558.  the CONTROLLER setting; this modification is described in the relevant "Beware"
  1559.  file in a note dated 89/2/27.
  1560. 0Catch  Two  is  that  the status order is not implemented in all of the devices
  1561.  that support Yale-ASCII-style transparent mode.  This means that  some  devices
  1562.  "fall  through  the  cracks"  in this procedure.  A site where such devices are
  1563.  used may find it expedient to modify Kermit (following the same  "Beware"  pat-
  1564.  tern)  to  force the procedure to set CONTROLLER to SERIES1 (assuming there are
  1565.  no other protocol converters also in use that support one of the  other  trans-
  1566.  parent modes).  A list of such devices can be found in a footnote in the Kermit
  1567.  distribution file ik0aaa.hlp.
  1568. 0
  1569.  Recognizing a 3174
  1570. 0The second diagnostic test uses a hardware command (Read Partition Query)  that
  1571.  is  defined  by  IBM, but is not implemented on all 3270-type equipment.  There
  1572.  is, thus, the same danger as in the first test, but the danger  appears  to  be
  1573.  slight.    Indeed,  both  CMS  and  TSO allow a user program to know in advance
  1574.  whether a Query is permitted.  The Query  response  consists  of  one  or  more
  1575.  structured fields, and the 3174 AEA ASCII Graphics system (the only device with
  1576.  the AEA style of transparency) is easily identified by the appearance and  con-
  1577.  tent  of  a particular type of field.  In fact, it is possible to tell from the
  1578.  Query data whether the particular  3174  line  is  allowed  to  use  the  ASCII
  1579.  Graphics  transparency.  Therefore, this test has three possible outcomes: Ker-
  1580.  mit may detect a transparency-enabled 3174 line (and set CONTROLLER to AEA); it
  1581.  may  detect  an  incapable  3174  line  (and set CONTROLLER to NONE); or it may
  1582.  detect "none of the above" (and set CONTROLLER to GRAPHICS).  Thus, aside  from
  1583.  the  exceptions  already noted, GRAPHICS simply means that the front end either
  1584.  supports SAS-style transparency or none at all.
  1585. 0
  1586.  Fallback positions
  1587. 0What should you do when the automatic detection fails?   Obviously,  the  first
  1588.  thing is Be Prepared.  Often, the misbehavior of VTAM can be halted by pressing
  1589.  ENTER or PA1, so you should be sure to know how to generate a PA1  when  trying
  1590.  out  Kermit on an unfamiliar type of protocol converter.  Also, you should know
  1591.  what kind of  transparency  to  expect  for  the  front  end  and  verify  that
  1592.  Kermit-370 has, in fact, set CONTROLLER appropriately.  This means checking the
  1593.  list of devices in the Kermit distribution file ik0aaa.hlp.  If your configura-
  1594.  tion  is  listed  as unsupported, you may be wasting your time, but the list is
  1595.  not necessarily up-to-date.  If your configuration is not listed  at  all,  you
  1596.  have  the opportunity to be a pioneer and report your findings back to Columbia
  1597.  for inclusion in future editions of the list.  There are a few rules  of  thumb
  1598.  for quickly deducing the controller type by reading the manuals for the device;
  1599. 11.6. Trouble-shooting Protocol Converters                               Page 34
  1600. 0-------------------------------------------------------------------------------
  1601.  the manuals may not be specific enough, but this is clearly the easiest way  of
  1602.  determining whether Kermit can support a given device and which controller type
  1603.  is applicable.    The  rules  are  as  follows  (in  order  of  simplicity  and
  1604.  likelihood):
  1605. 0   1. GRAPHICS or SERIES1 may be implied when the device has a transparent
  1606.        or graphics mode described as compatible with that  of  a  supported
  1607.        device listed in ik0aaa.hlp.
  1608. 0   2. SERIES1  is  implied when the device runs the "Yale ASCII Communica-
  1609.        tion System" or something with a similar name.
  1610. 0   3. GRAPHICS is implied if the manual mentions the SAS Institute in  the
  1611.        context of ASCII graphics.
  1612. 0   4. GRAPHICS  is implied when output transparent data may be preceded by
  1613.        a WCC (Write Control Character) and 70 (hex).
  1614. 0   5. SERIES1 is implied when transparent data must be preceded by  a  WCC
  1615.        and either 115D7F110005 (write-read) or 115D7F110000 (write-only).
  1616. 0   6. GRAPHICS  or  SERIES1 may be implied when some of the manufacturer's
  1617.        other products are listed in ik0aaa.hlp, and all are shown as  being
  1618.        of one type.
  1619. 0   7. If  none of the above rules apply, but the manuals describe a trans-
  1620.        parent mode in detail, the device may be a totally new  type.    The
  1621.        distribution  file  ik0con.hlp has hints on implementing Kermit sup-
  1622.        port for the new type.
  1623. 0   8. If nothing else works, you can probably use FULLSCREEN mode, as long
  1624.        as the micro Kermit supports it.
  1625. 0If  Kermit tries to transfer a file with the wrong CONTROLLER value, there is a
  1626.  distressing possibility for the session to lock or, at least, appear  to  lock.
  1627.  When  and  if  this  happens,  be  sure  to connect back to the mainframe, type
  1628.  "STOP", and press ENTER several times (perhaps as  many  as  15  times)  before
  1629.  taking any drastic steps like breaking the connection.  "STOP" is a special es-
  1630.  cape mechanism for getting out of Kermit protocol  mode  quickly.    Kermit-370
  1631.  recognizes such a request in most situations where terminal I/O is not entirely
  1632.  frozen.  Sometimes, apparent lock-ups are due to something as simple as  incor-
  1633.  rect  parity settings in the micro Kermit, so always check the basic communica-
  1634.  tion settings and, if necessary, experiment  before  trying  a  different  CON-
  1635.  TROLLER type.  Also, to avoid unnecessary confusion, check for the existence of
  1636.  a Kermit initialization file (possibly created by the installer) which could be
  1637.  re-setting  CONTROLLER  after  the  automatic  procedure  has finished.  Such a
  1638.  re-setting is a poor idea in an initialization file, even a personal  one,  un-
  1639.  less there is absolutely only one kind of communications equipment on your sys-
  1640.  tem.
  1641. 0If file transfers do not work at first, it is best to do the  following  before
  1642.  trying again:
  1643. 0   1. Reduce the packet size to no more than 80 at both ends.
  1644. 0   2. Enable 8th-bit quoting at both ends.
  1645. 11.6. Trouble-shooting Protocol Converters                               Page 35
  1646. 0-------------------------------------------------------------------------------
  1647.     3. Set SEND PARITY MARK in Kermit-370.
  1648. 0If  those  changes do not make transfers work, the next remedial action depends
  1649.  on the symptoms of failure.
  1650. 0   - No packets exchanged and session locked up after reconnecting: change
  1651.       packet characters in both directions.
  1652. 0   - No  packets  exchanged,  but  no  lockup: change packet characters or
  1653.       parity.
  1654. 0   - Always multiple retries of third or fourth packet:  reduce  receiving
  1655.       packet size.
  1656. 0   - Multiple  retries  after random number of packets: check hardware and
  1657.       cables.
  1658. 0   - Multiple retries after file-dependent number of  packets:  check  for
  1659.       equipment  that intercepts one or more printable characters or reduce
  1660.       the packet size.
  1661. 0When all else fails, you should be ready to reset CONTROLLER by  hand  and  try
  1662.  again.    The  change  most likely to be necessary is from GRAPHICS to SERIES1.
  1663.  However, it is conceivable that the installer has modified Kermit-370  at  your
  1664.  location  to  force  the  CONTROLLER setting from the start, in which case, you
  1665.  might need to go the other way.  Normally,  Kermit's  diagnostic  procedure  at
  1666.  start-up takes one or two seconds (because of programmed delays), so you should
  1667.  be suspicious if the Kermit prompt appears  immediately  after  you  start  the
  1668.  program.    The  only  initial CONTROLLER setting that you should not change by
  1669.  hand is NONE, which means that Kermit-370 has recognized a 3174 AEA  line  that
  1670.  is  not configured for file transfer (or else the Kermit installer has a warped
  1671.  sense of humor).
  1672. 0If no amount of experimenting gets a transparent mode to work, it  is  time  to
  1673.  recheck  the list of supported devices and the age of your equipment.  If yours
  1674.  is very old, it may require new microcode or some other  software  or  hardware
  1675.  upgrade.    In any case, if your results (whether positive or negative) are not
  1676.  already shown in ik0aaa.hlp, you should report them to Columbia so that  others
  1677.  may profit by your experience.
  1678. 0
  1679.  1.7. After Returning from Kermit-370
  1680. 0When  Kermit-370  receives a QUIT or EXIT subcommand or finishes the subcommand
  1681.  or subcommands specified in the original command string  that  invoked  Kermit,
  1682.  control is returned to the caller.  Before returning, Kermit-370 closes any ac-
  1683.  tive TAKE files (the EXIT or QUIT subcommand may be issued from a  TAKE  file).
  1684.  On  return,  the completion code is set from the current error status according
  1685.  to the codes in Table 1-4.
  1686. 0The error codes in Table 1-4 bear no relationship to the severity  of  the  as-
  1687.  sociated error conditions, aside from the assignment of code 0.  The underlying
  1688.  rationale is that the only current generic system for the treatment of  comple-
  1689.  tion  codes is to take a non-zero code as an indication of error.  Indeed, Ker-
  1690.  mit returns a completion code of 0 when "error" condition 1 holds.
  1691. 11.8. What's New                                                         Page 36
  1692. 0-------------------------------------------------------------------------------
  1693.  -------------------------------------------------------------------------------
  1694. 0
  1695.  Code  Symbol  Error Message
  1696.   0    NOE     No errors
  1697.   1    NFT     No file transfers yet
  1698.   2    TRC     Transfer cancelled
  1699.   3    USC     Invalid server command
  1700.   4    TIE     Terminal I/O error
  1701.   5    BPC     Bad packet count or chksum
  1702.   6    IPS     Invalid packet syntax
  1703.   7    IPT     Invalid packet type
  1704.   8    MIS     Lost a packet
  1705.   9    NAK     Micro sent a NAK
  1706.  10    ABO     Micro aborted
  1707.  11    FNE     Invalid file name
  1708.  12    FNF     File not found
  1709.  13    FUL     Disk or file is full
  1710.  14    DIE     Disk I/O error
  1711.  15    MOP     Missing operand
  1712.  16    SYS     Illegal system command
  1713.  17    KCE     Kermit command error
  1714.  18    TIM     No packet received
  1715.  19    RTR     Records truncated
  1716.  20    COM     Bad communication line
  1717.  21    PTY     8th-bit quote not set
  1718.  22    FTS     File too short
  1719.  23    SOH     Missing start-of-packet
  1720.  24    OPT     Option error on filespec
  1721.  25    DSP     Unable to dispose of file
  1722. 0              Table 1-4:  Error messages and codes for Kermit-370
  1723. 0
  1724. 0-------------------------------------------------------------------------------
  1725. 0
  1726.  1.8. What's New
  1727. 0Below is a list of the changes in Version 4.2.3 of Kermit-370.
  1728. 0   1. Compatibility with the (aging) F-level assembler.
  1729. 0   2. Support for LATIN2, LATIN3, TRANSPARENT, CP870, CP905, and CP880, as
  1730.        well as the aliases L1, L2, and L3.
  1731. 0   3. Support for IBM 3174 ASCII Graphics mode.
  1732. 0   4. Support for REMOTE PRINT, REMOTE MAIL, and REMOTE SUBMIT.
  1733. 0   5. Improved  error message for bad packet-size, new alias PACKET-LENGTH
  1734.        for PACKET-SIZE.
  1735. 0   6. Correct observance of FILE COLLISION for all files in a group.
  1736. 0   7. Ignoring  spurious  flow-control  "packets"   from   (for   example)
  1737. 11.8. What's New                                                         Page 37
  1738. 0-------------------------------------------------------------------------------
  1739.        MS-Kermit.
  1740. 0   8. Support for new locking-shift Kermit protocol.
  1741. 0   9. Support for Japanese Kanji file transfer.
  1742. 0  10. New FULLSCREEN controller type.
  1743. 0  11. New HINTS subcommand.
  1744. 0  12. More graceful recovery from terminal I/O errors and exceptions.
  1745. 0  13. Support for SNA LU1 3770-type devices and 8-bit, no-parity devices.
  1746. 0  14. Automatic  conversion  of EBCDIC printer carriage control into ASCII
  1747.        control characters.
  1748. 0  15. Support for STOP command on "dumb" 3270 terminals and  PCI  protocol
  1749.        converters.
  1750. 0  16. New efficiency display in STATUS report, based on SPEED setting.
  1751. 0  17. 8-bit XECHO output.
  1752. 0  18. Control prefixing for C1 controls.
  1753. 0  19. New VERSION subcommand.
  1754. 0  20. Improved debugging facilities.
  1755. 0
  1756.  1.9. What's Missing
  1757. 0Work  on  Kermit-370 will continue.  Features that need to be improved or added
  1758.  include:
  1759. 0   - Implement file archiving.
  1760. 0   - Implement file transfer checkpointing.
  1761. 0   - Add SET REPEAT subcommand.
  1762. 0   - Improve Kermit-370 operation as a local Kermit.
  1763. 0   - Implement public server mode.
  1764. 0   - Add new SET FILE LONGLINE DISCARD option to allow multi-file transfer
  1765.       to proceed past a truncation problem.
  1766. 0   - System-specific upgrades; see the respective chapters for details.
  1767. 0Anyone interested in working on these or other improvements should first get in
  1768.  touch with the Center for Computing Activities at Columbia University  to  find
  1769.  out if someone else has already begun a similar project (and, if so, who).
  1770. 11.10. Further Reading                                                   Page 38
  1771. 0-------------------------------------------------------------------------------
  1772.  1.10. Further Reading
  1773. 0Below is a list of references for some of the material in this chapter.
  1774. 0   1. About  Type:  IBM's  Technical Reference for 240-Pel Digitized Type,
  1775.        S544-3156-02 (1989).  This manual contains  visual  tables  of  many
  1776.        EBCDIC  code  pages  and a comprehensive list of character names and
  1777.        acronyms.
  1778. 0   2. IBM System/370 Reference Summary, GX20-1850-3 (1976).   This  refer-
  1779.        ence card contains EBCDIC and ASCII character codes.
  1780. 0   3. IBM   VS   Fortran   Application  Programming:  Language  Reference,
  1781.        GC26-3986-1 (1982).  Appendix E contains a table of EBCDIC and ASCII
  1782.        characters with an implied full 256-byte translation table.
  1783. 0   4. IBM  3174  Character  Set Reference, GA27-3831-02 (1990).  Chapter 5
  1784.        contains visual tables of many EBCDIC code pages.
  1785. 0   5. Info-Kermit Digest Vol. 11 #1 (1989).   This  issue  contains  draft
  1786.        specifications of some Kermit protocol extensions.
  1787. 0   6. ISO  International  Register of Coded Character Sets to be used with
  1788.        Escape Sequences (1989).  This (very large)  document  has  complete
  1789.        and  unambiguous  descriptions of standard coded character sets.  It
  1790.        can be obtained from the ECMA.
  1791. 0   7. Kermit, A File Transfer Protocol by Frank  da  Cruz;  Digital  Press
  1792.        (1987).    This  book  contains a thorough description of the Kermit
  1793.        protocol and services with copious examples.
  1794. 0   8. Kermit distribution file ISOK5.TXT (1990).  This  preliminary  draft
  1795.        describes  the  new  transfer  protocol, including the international
  1796.        character-set support.
  1797. 0   9. Kermit News Vol. 3 #1, p.5, "Dynamic Packet  Size  Control"  (1988).
  1798.        This article describes an algorithm for optimizing Kermit throughput
  1799.        in the face of line noise.
  1800. 0  10. Kermit News #4, p.16, "International Character Sets" (1990).    This
  1801.        article discusses the new transfer protocol.
  1802. 0  11. ASCII  and  EBCDIC Character Set and Code Issues in Systems Applica-
  1803.        tions Architecture, SHARE white paper by Edwin Hart  (1989).    This
  1804.        document,  available as file SHARE REQUIRE from LISTSERV@JHUVM, lays
  1805.        out general considerations for character codes and translatability.
  1806. 12. IBM MVS/TSO KERMIT                                                   Page 39
  1807. 0-------------------------------------------------------------------------------
  1808.  2. IBM MVS/TSO KERMIT
  1809. 0Program:       John Chandler  (Harvard/Smithsonian  Center  for  Astrophysics);
  1810.                 contributions  from Vace Kundakci and Daphne Tzoar (Columbia U),
  1811.                 Bob Shields (U. Maryland), Greg Small (UC Berkeley),  Bob  Bolch
  1812.                 and  Steve  Blankinship  (Triangle),  Ron  Rusnak  (U. Chicago),
  1813.                 Charles Painter (U.  Toronto),  Roger  Fajman  and  Dale  Wright
  1814.                 (NIH), Andre Pirard (U. Liege)
  1815.  Language:      IBM/370 Assembler
  1816.  Documentation: John Chandler (CfA)
  1817.  Version:       4.2.0 (90/3/13)
  1818.  Date:          1990 May
  1819. 0
  1820.  Kermit-TSO Capabilities At A Glance:
  1821. 0  Local operation:                   No
  1822.    Remote operation:                  Yes
  1823.    Transfers text files:              Yes
  1824.    Transfers binary files:            Yes
  1825.    Wildcard send:                     Yes
  1826.    ^X/^Z interruption:                Yes (through micro)
  1827.    Filename collision avoidance:      Yes
  1828.    Can time out:                      Yes (line mode only)
  1829.    8th-bit prefixing:                 Yes
  1830.    Repeat count prefixing:            Yes
  1831.    Alternate block checks:            Yes
  1832.    Terminal emulation:                No
  1833.    Communication settings:            No
  1834.    Transmit BREAK:                    No
  1835.    Packet logging:                    Yes
  1836.    Transaction logging:               Yes
  1837.    Session logging:                   No
  1838.    Raw transmit:                      Yes (no prompts)
  1839.    Sliding window:                    No
  1840.    Long packets:                      Yes
  1841.    Act as server:                     Yes
  1842.    Talk to server:                    Yes
  1843.    Advanced server functions:         Yes
  1844.    Advanced commands for servers:     Yes
  1845.    Local file management:             Yes
  1846.    Handle Attribute Packets:          Yes
  1847.    Command/init files:                Yes
  1848.    Command macros:                    No
  1849. 0
  1850.  TSO Specifics of Kermit-370:
  1851. 0  Global INIT file:                  'SYS1.KERMINI'
  1852.    User INIT file:                    KERMINI
  1853.    Debug packet log:                  KER.LOG
  1854.    Server reply log:                  KER.REPLY
  1855.    Mail command:                      KERMAIL filespec LIST(users)
  1856.    Print command:                     KERMPRT filespec OPTIONS(options)
  1857.    Submit command:                    KERMSUB filespec OPTIONS(options)
  1858.    Maximum packet size:               1913 (SERIES1), 1024 (TTY)
  1859. 12. IBM MVS/TSO KERMIT                                                   Page 40
  1860. 0-------------------------------------------------------------------------------
  1861.    Maximum disk LRECL:                32760
  1862. 0Kermit-TSO  is a member of the generic Kermit-370 family and shares most of the
  1863.  features and capabilities of the group.  As its name implies, Kermit-TSO is the
  1864.  variant  of  Kermit-370  that  runs  under  the  MVS/TSO operating system.  The
  1865.  primary documentation for Kermit-TSO is actually the chapter on Kermit-370 (en-
  1866.  titled IBM 370 Kermit), which describes general properties; the present chapter
  1867.  assumes the reader is familiar with that material.  Only the  details  specific
  1868.  to  TSO  operation will be discussed here, e.g., command syntax relating to the
  1869.  TSO file system or commands not offered in general by Kermit-370.
  1870. 0
  1871.  2.1. The MVS/TSO File System
  1872. 0The features of the TSO file system of greatest interest to  Kermit  users  are
  1873.  the  format of file specifications (filespecs) and the concept of records.  The
  1874.  latter is described in the Kermit-370 chapter.
  1875. 0The MVS/TSO filespec (called the data set name or DSN) takes the form of tokens
  1876.  (known  as  qualifiers)  of  up to 8 alphanumeric characters each, separated by
  1877.  periods.  Each qualifier must begin with an alphabetic or  national  character.
  1878.  The  total length must be no more than 44 characters, including periods.  To be
  1879.  precise, a DSN may contain uppercase letters, digits, and the  special  charac-
  1880.  ters  "$"  (dollar sign), "#" (number sign), "@" (at sign), and "-" (hyphen) in
  1881.  addition to the separating periods.  Other characters must not be included.
  1882. 0There is another, structural restriction on data set names from the  fact  that
  1883.  TSO  data sets are all cataloged.  In a standard MVS catalog, each qualifier of
  1884.  each DSN is associated with an index of the same name.  The index is a  hierar-
  1885.  chical  catalog  component which points downward either to a list of next-level
  1886.  indices or to a data set, but never to both.  Consequently, a cataloged DSN  is
  1887.  a  chain  of indices corresponding one-for-one with DSN qualifers, and the last
  1888.  index is a pointer to the data set itself.  While there  may  be  many  indices
  1889.  with  the  same  name,  no  two such duplicates may both be chained to the same
  1890.  next-higher-level index, so  that,  if  DSN's  are  considered  as  strings  of
  1891.  qualifiers  (not  of characters), no DSN can be a major substring of any other.
  1892.  For example, if the name 'A.BB.C'  exists  in  the  catalog,  then  'A.BB'  and
  1893.  'A.BB.C.X'  are  illegal,  but  'A.B', 'A.BB.Y', 'A.BBB', and 'A.BB.BB' are all
  1894.  legal.  Although there is a newer form of catalog, known as IFC, which  removes
  1895.  this substring restriction, it is still good practice to avoid violating it be-
  1896.  cause there are still sites that use the older form.
  1897. 0A DSN given in its entirety (as in the foregoing  examples)  is  called  "fully
  1898.  qualified" and must be enclosed in single quotes when entered in TSO.  However,
  1899.  by convention (and by definition) the first qualifier of each data set  belong-
  1900.  ing  to  a  given user must be the user's logon ID, and, by default, that ID is
  1901.  the assumed prefix in TSO when a DSN is not enclosed in quotes.   In  practice,
  1902.  then,  names  are  abbreviated by omitting the quotes and the prefix.  The most
  1903.  common type of name, in fact, consists of the prefix plus two  more  qualifiers
  1904.  giving  the  data  set's  name  and type, respectively, so that many files have
  1905.  DSN's that correspond exactly to  the  canonical  Kermit  representation  of  a
  1906.  filespec.    For  instance,  TEST.FORT is the source of a Fortran program named
  1907.  TEST, and its fully qualified DSN would be 'userid.TEST.FORT', where userid  is
  1908.  the owner's logon ID.
  1909. 0While  this  description  is  complete as far as it goes, it omits an important
  1910. 12.1. The MVS/TSO File System                                            Page 41
  1911. 0-------------------------------------------------------------------------------
  1912.  feature that is widely used in organizing files under MVS and TSO, namely,  the
  1913.  partitioned data set (PDS).  A PDS is a data set like any other, except that it
  1914.  has members, each of which can usually be treated as a file in its  own  right.
  1915.  In  fact,  with  QSAM (the file access method employed by Kermit and many other
  1916.  applications), only members, and not the whole PDS, may  be  read  or  written.
  1917.  Thus,  the term "file", as used in this chapter and the Kermit-370 chapter, may
  1918.  refer to either a PDS member or an ordinary data set, but not to a  PDS.    The
  1919.  notation  for  a PDS member consists of the member name enclosed in parentheses
  1920.  and appended to the DSN (and the whole enclosed in quotes if the DSN  is  fully
  1921.  qualified).    For  example, if the Fortran program TEST were copied into a PDS
  1922.  called DEBUG.FORT, it would then be known as
  1923. 0  DEBUG.FORT(TEST)
  1924. 0Although the member name is written together with the DSN, it and the surround-
  1925.  ing  parentheses  are not really part of the DSN and are not counted toward the
  1926.  44-character limit.  Still, a member name must conform to the rules for  a  DSN
  1927.  qualifier and, in addition, must not contain any hyphens.
  1928. 0All  these  properties of DSN's come into play when a file is being received by
  1929.  Kermit-TSO because a valid DSN must be generated for the new data set.  For ex-
  1930.  ample,  any  invalid character in the supplied filespec is replaced by a number
  1931.  sign (or converted to uppercase if it is  a  lowercase  letter).    Also,  each
  1932.  qualifier  (and  the member name, if any) is prefixed with a number sign (if it
  1933.  does not already begin with an alphabetic or national character) and then shor-
  1934.  tened,  if  necessary,  to  eight  characters.    If  no  filespec is supplied,
  1935.  Kermit-TSO creates a default DSN of "$.$".  The DSN is expanded  to  its  fully
  1936.  qualified form and then truncated at 44 characters, if need be.
  1937. 0The  DSN  prefix, which defaults to the user's logon ID, is similar to a device
  1938.  specification on microcomputer systems: it selects an area of disk storage, and
  1939.  it usually need not be specified.  In some ways, the prefix is also like a disk
  1940.  directory designator, since the file system structure  is  hierarchical.    For
  1941.  this  reason,  the  Kermit concept of the "working directory" is equated with a
  1942.  particular DSN prefix under Kermit-TSO.  The current "working directory" is the
  1943.  collection of all data sets whose names begin with the current prefix, and file
  1944.  transfers take place to and from that area unless  a  fully  qualified  DSN  is
  1945.  given.
  1946. 0To  provide compatibility with other operating systems, when Kermit-TSO sends a
  1947.  file, it ordinarily makes a file header with only the last  two  qualifiers  of
  1948.  the  full DSN (or only the member name plus the last qualifier in the case of a
  1949.  PDS member).  On the other hand, extra information may be added by way  of  the
  1950.  SET FOREIGN subcommand.
  1951. 0Although  TSO  data  sets  are  cataloged, MVS allows uncataloged data sets  as
  1952.  well, and Kermit-TSO can download such files, as long as the user specifies the
  1953.  proper  disk  volume  via  the  SET  FILE VOLUME subcommand.  In principle, un-
  1954.  cataloged data sets may have names with illegal characters or qualifiers longer
  1955.  than 8 characters, but such names are not recognized by Kermit-TSO.
  1956. 0Kermit-TSO  allows a group of files to be specified in a single filespec by in-
  1957.  cluding the special "wildcard" character  "*",  which  matches  any  string  of
  1958.  characters  (even  a  null  string) anywhere either in the DSN proper or in the
  1959.  member name, if any.  Only one * may be used in a filespec.  Here are some  ex-
  1960.  amples:
  1961. 12.1. The MVS/TSO File System                                            Page 42
  1962. 0-------------------------------------------------------------------------------
  1963.    *.COBOL         All  files of type COBOL (all COBOL source files) in the cur-
  1964.                    rent working directory.
  1965. 0  BATCH*H.FORT    All files in the current directory which begin with BATCH and
  1966.                    which  end  with  H.FORT.  This would not include BATCH.FORT,
  1967.                    however.
  1968. 0TSO files, like those in other IBM 370 systems, are  record-oriented  (see  the
  1969.  introduction  to the Kermit-370 chapter).  In particular, TSO files are charac-
  1970.  terized by record format (RECFM), which may be fixed-length, varying-length, or
  1971.  undefined-length;  by  maximum record length (LRECL); and by maximum block size
  1972.  (BLKSIZE).  Fixed-length and varying-length records can be (and, under  Kermit,
  1973.  always are) combined into blocks, but undefined-length records cannot.  Indeed,
  1974.  by convention, they have no logical record length, only a maximum  block  size.
  1975.  Records  (and  blocks)  in  TSO  files  may  be  up  to  32760  bytes long, but
  1976.  varying-length record blocks use four bytes to specify the  block  length  and,
  1977.  therefore,  place an effective limit of 32756 on the records.  Indeed, the data
  1978.  portion of such records is limited to 32752 bytes.
  1979. 0Another file system feature of occasional interest is the  means  of  reporting
  1980.  errors.  When Kermit-TSO encounters a disk error, it attempts to prepare an ex-
  1981.  planatory message for inclusion in the STATUS report.  The  primary  method  is
  1982.  the standard SYNADAF macro.
  1983. 0MVS/TSO  allows,  but  does not encourage, the use of passwords  to protect in-
  1984.  dividual data sets.  When a password is needed for file access, it  is  entered
  1985.  immediately  after  the filespec, separated only by a slash ("/").  In the case
  1986.  of a fully-qualified DSN, the password must  be  after  the  closing  quotation
  1987.  mark.
  1988. 0
  1989.  2.2. Program Operation
  1990. 0At  startup time, Kermit-TSO looks for two initialization files, 'SYS1.KERMINI'
  1991.  and 'userid.KERMINI' (where, as before, userid is the user's logon  ID).    The
  1992.  latter file would also be known as just KERMINI.  The file 'SYS1.KERMINI' would
  1993.  be maintained by a systems programmer, but KERMINI would be maintained  by  the
  1994.  user.
  1995. 0Three  parameters  in  the user's profile (the character delete and line delete
  1996.  and intercom) are disabled during protocol mode (and  restored  afterwards)  to
  1997.  prevent  any conflict in case either of these characters has been defined to be
  1998.  printable.  The settings in effect when Kermit starts up are saved as a sort of
  1999.  "normal"  status snapshot (as opposed to the "protocol" status just described).
  2000.  The protocol status is selected whenever Kermit enters protocol mode,  and  the
  2001.  normal status is selected when Kermit leaves protocol mode.  Note: if Kermit is
  2002.  interrupted in the  midst  of  a  transfer  or  while  in  server  mode,  these
  2003.  parameters  will  be left with peculiar settings (namely, the protocol status),
  2004.  and they may need to be restored by hand.
  2005. 0Although TSO does not allow an application program to take control of  terminal
  2006.  synchronization  on  "TTY"  lines, the various full-screen emulation front ends
  2007.  are quite a different matter.  The standard IBM handshake (XON) is unnecessary,
  2008.  for  example,  with  a 7171 or 4994 because the front end itself turns the line
  2009.  around with essentially no delay in transparent mode.  Thus, handshaking should
  2010.  be suppressed for "SERIES1" devices (the micro Kermit should have HANDSHAKE set
  2011. 12.2. Program Operation                                                  Page 43
  2012. 0-------------------------------------------------------------------------------
  2013.  OFF, and Kermit-TSO should have  HANDSHAKE  set  to  0).    Since  the  generic
  2014.  Kermit-370  default  handshake  (XON) is retained in Kermit-TSO, the subcommand
  2015.  "SET HANDSHAKE 0" is a good candidate for inclusion the  KERMINI  file  of  any
  2016.  user who habitually uses "SERIES1" lines.
  2017. 0
  2018.  Interactive Operation:
  2019. 0To  run Kermit-TSO interactively, invoke the program from TSO by typing KERMIT.
  2020.  When you see the prompt,
  2021. 0  Kermit-TSO>
  2022. 0you may type a Kermit subcommand.  When the subcommand completes, Kermit issues
  2023.  another  prompt.    The cycle repeats until you exit from the program.  For ex-
  2024.  ample:
  2025. 0  .KERMIT
  2026. 0  Kermit-TSO Version 4.2.0 (90/3/13)
  2027.    Enter ? for a list of valid commands
  2028. 0  Kermit-TSO>send foo.*
  2029. 0    Files beginning with FOO are sent
  2030. 0  Kermit-TSO>receive test.spss
  2031. 0    File is received and called TEST.SPSS
  2032. 0  Kermit-TSO>exit
  2033. 0
  2034.  Command Line Invocation:
  2035. 0Kermit-TSO may also be invoked with command line arguments from TSO.   The  ar-
  2036.  guments  are interpreted as a subcommand to be executed by Kermit after comple-
  2037.  tion of the initialization.  For instance:
  2038. 0  .KERMIT send test.fort
  2039. 0Kermit will exit and return to TSO after completing the specified subcommand.
  2040. 0
  2041.  CLIST Operation:
  2042. 0Like other TSO programs, Kermit-TSO may be invoked from a CLIST.    Subcommands
  2043.  can  be  passed to Kermit using the program input stack and/or command line ar-
  2044.  guments.  For example, to start up Kermit-TSO and have it act as a server,  in-
  2045.  clude the line:
  2046. 0  KERMIT server
  2047. 0To  pass  more  than one subcommand, they must be stacked in the order in which
  2048.  they are to be executed.  To start up a Kermit-TSO server with a three  charac-
  2049.  ter CRC, create and stack a file with the following:
  2050. 12.2. Program Operation                                                  Page 44
  2051. 0-------------------------------------------------------------------------------
  2052.    set block 3
  2053.    server
  2054. 0and  then  invoke  Kermit.    Like  many  utility programs, Kermit-TSO uses the
  2055.  GETLINE/PUTLINE service routines for terminal I/O,  and  the  nominally  inter-
  2056.  active  subcommands can thus be supplied under program control.  Another way of
  2057.  setting up multiple subcommands would be to collect the subcommands into a TAKE
  2058.  file  and  then issue the TAKE subcommand via the command line.  CLIST's may be
  2059.  executed from Kermit, either directly or from a TAKE file, and CLIST's in  turn
  2060.  may  freely issue Kermit subcommands.  The subcommand KERMIT is especially use-
  2061.  ful in this context for distinguishing Kermit subcommands from TSO commands.
  2062. 0
  2063.  Server mode:
  2064. 0Command execution in server mode is different in several respects  from  normal
  2065.  operation.  First of all, some Kermit subcommands are not allowed (see the list
  2066.  of subcommands in the Kermit-370 chapter).   Moreover,  command  errors  always
  2067.  terminate  any  active  TAKE file.  Also, commands run in a special environment
  2068.  with the User Profile temporarily modified.  Another difference is that  Kermit
  2069.  intercepts terminal I/O as much as possible and transmits the data to the local
  2070.  Kermit as text packets.  The problem with this redirection is that some MVS/TSO
  2071.  commands issue terminal I/O directly, so that many messages never appear to the
  2072.  local Kermit (except, perhaps, as bad packets).
  2073. 0
  2074.  2.3. Kermit-TSO Subcommands
  2075. 0Kermit-TSO supports all the subcommands described in  the  Kermit-370  chapter.
  2076.  In  addition,  there  is  the system-specific subcommand "TSO", which is just a
  2077.  synonym for the generic subcommand "HOST".  "TSO" can be  issued  as  a  remote
  2078.  Kermit  command  when Kermit-TSO is in server mode.  Also, the "END" subcommand
  2079.  is available as a synonym for "EXIT" and "QUIT".
  2080. 0This section concentrates on the subcommands that have special form or  meaning
  2081.  for  Kermit-TSO.    These  are  ordered  alphabetically.    See  the chapter on
  2082.  Kermit-370 for further details.
  2083. 0
  2084.                                THE CWD SUBCOMMAND
  2085. 0Syntax: CWD [string or PDSname()]
  2086. 0The CWD (Change Working Directory) subcommand establishes  a  new  default  DSN
  2087.  prefix  or turns prefixing off.  This facility is similar to, but not quite the
  2088.  same as, the prefix defined in the User Profile.   The  string,  if  specified,
  2089.  must  consist  of  one or more DSN qualifiers, and the first must already be an
  2090.  index in the disk catalog.  Subsequent file transfers take place  to  and  from
  2091.  the  corresponding  disk  area  whenever a fully qualified DSN (one enclosed in
  2092.  quotes) is not given.  The initial prefix is the user's  logon  ID,  i.e.,  the
  2093.  same  as the default prefix in the User Profile.  If no prefix is given in this
  2094.  subcommand, then prefixing is no longer performed.  The user must be careful to
  2095.  remember  the  distinction  between  the prefix defined for Kermit and that for
  2096.  TSO.  Pure Kermit subcommands (like SEND and TAKE) always use the  former,  but
  2097.  TSO commands (and the TSO-related subcommand TYPE) use the latter.
  2098. 0An  alternative  form of the CWD subcommand allows specifying the full (but un-
  2099. 12.3. Kermit-TSO Subcommands                                             Page 45
  2100. 0-------------------------------------------------------------------------------
  2101.  quoted) name of a PDS followed by paired parentheses.   When  such  a  "working
  2102.  directory"  is  in use, a filespec other than a fully qualified DSN is taken to
  2103.  be a member name within the PDS.  For that reason, this  form  should  be  used
  2104.  cautiously,  since the Kermit-TSO log filespecs (such as KER.LOG and KER.REPLY)
  2105.  would be treated the same way.  In particular, it is advisable to turn on debug
  2106.  mode  only  when  the Kermit prefix is a partially qualified DSN (once started,
  2107.  the log continues to the same data  set  regardless  of  what  happens  to  the
  2108.  prefix).
  2109. 0
  2110.                             THE DIRECTORY SUBCOMMAND
  2111. 0Syntax: DIRECTORY [filespec]
  2112. 0The  DIRECTORY  subcommand  uses the TSO LISTCAT command to display part of the
  2113.  data set catalog, i.e., all data sets whose names begin with the qualifiers  in
  2114.  the  Kermit  prefix  (if  any)  concatenated  with the given filespec (if any).
  2115.  Note: wildcards may not be used, and no options are allowed.   If  you  require
  2116.  the LISTCAT options, you must issue a TSO LISTCAT command directly.
  2117. 0
  2118.                                THE HELP SUBCOMMAND
  2119. 0Syntax: HELP [subcommand]
  2120. 0The HELP subcommand uses TSO HELP facilities to display part or all of the Ker-
  2121.  mit help file.  It follows the same syntax.
  2122. 0
  2123.                              THE RECEIVE SUBCOMMAND
  2124. 0Syntax: RECEIVE [filespec]
  2125. 0The RECEIVE subcommand tells Kermit to receive a file or file  group  from  the
  2126.  other  system.    You must issue the corresponding SEND subcommand to the other
  2127.  Kermit.
  2128. 0A filespec in the subcommand indicates what name the incoming  file  should  be
  2129.  given.  Wildcards may not be used.  If the filespec is invalid, Kermit-TSO will
  2130.  suppress the transfer.  If the optional filespec is omitted (and, in any  case,
  2131.  for  all  files  after  the  first  in a group) Kermit-TSO will use the name(s)
  2132.  provided by the other Kermit.  If a name is not a legal  DSN,  Kermit-TSO  will
  2133.  delete excess characters, change illegal characters to number signs, and so on,
  2134.  to create a legal name.
  2135. 0For the purposes of folding and truncation, the maximum  record  length,  i.e.,
  2136.  the  limit  on  the  length  of  data in each record, is "LRECL" if RECFM is F,
  2137.  "LRECL"-4 if RECFM is V, and "BLKSIZE" if RECFM is U.
  2138. 0If the incoming file has the same name as an existing file (either a  data  set
  2139.  or  a PDS member), the action taken depends on the FILE COLLISION setting.  The
  2140.  possible settings and their meanings are given in the Kermit-370 chapter.   Two
  2141.  of the settings (BACKUP and RENAME) require that Kermit-TSO change the incoming
  2142.  name so as not to obliterate the pre-existing file.   It  attempts  to  find  a
  2143.  unique  name by successively modifying the original and checking for the exist-
  2144.  ence of such a file at each  step.    The  procedure  operates  on  the  second
  2145. 12.3. Kermit-TSO Subcommands                                             Page 46
  2146. 0-------------------------------------------------------------------------------
  2147.  qualifier  of the full DSN (or the member name in the case of a PDS member) and
  2148.  begins by truncating it to seven characters, if  necessary,  and  then  appends
  2149.  "0".    If a file by that name exists, Kermit then replaces the "0" with a "1".
  2150.  It continues in this manner up to "9", and if an unused name cannot  be  found,
  2151.  the  transfer  fails.  If FILE COLLISION has not been set, but the obsolete op-
  2152.  tion WARNING has been set ON, however, Kermit-TSO will protect an existing file
  2153.  in  a  different  way when the filespec is entered with the RECEIVE subcommand.
  2154.  In that case, Kermit will prompt the user for permission to overwrite the file.
  2155. 0
  2156.                                THE SEND SUBCOMMAND
  2157. 0Syntax: SEND [filespec[<options>] [foreign-filespec]][, ...]
  2158. 0The SEND subcommand causes a file or file group to be sent from TSO to the Ker-
  2159.  mit  on  the  other system.  DSN prefixing is done on the filespec in the usual
  2160.  way (see also the CWD subcommand).  For details on the options, see the chapter
  2161.  on Kermit-370.  Note that a filespec may have both a password and options -- in
  2162.  that case, the options must be at the very end.  Blanks may not appear anywhere
  2163.  in the string.
  2164. 0The  filespec  may contain a wildcard "*".  If it does, then all matching files
  2165.  will be sent, up to 711 files in all (possibly more in the  case  of  PDS  mem-
  2166.  bers).
  2167. 0The foreign-filespec, if any, is used for the file header of the outgoing file,
  2168.  replacing the usual name.type derived from the  MVS/TSO  filespec.    Normally,
  2169.  this  form  of  the  SEND  subcommand is used only for single files because the
  2170.  foreign-filespec is used only for the first file of a group  (subsequent  files
  2171.  having  default  headers).   If both filespecs are omitted for this subcommand,
  2172.  Kermit will prompt separately for each, and the respective syntaxes are exactly
  2173.  as  described  above.   This prompting mode is especially useful when more than
  2174.  one file (or file group) is to be sent, since the command line  is  limited  to
  2175.  130 characters.
  2176. 0Trailing  blanks  in  a  text  file with RECFM=F are deemed superfluous and are
  2177.  stripped off when Kermit-TSO downloads the file.  In order to treat such blanks
  2178.  as  significant, you must convert the record format to V, for example, by using
  2179.  TSO COPY with the "RECFM V" option.
  2180. 0
  2181.                                THE SET SUBCOMMAND
  2182. 0Syntax: SET parameter [value]
  2183. 0The SET subcommand establishes or modifies various parameters controlling  file
  2184.  transfers.    The following SET parameters are available in Kermit-TSO, but not
  2185.  in Kermit-370 in general:
  2186. 0DELIM               Line delimiter for entering multiple commands.
  2187.  FILE
  2188.    BLKSIZE           Block size for incoming file.
  2189.    LRECL             Logical Record length for incoming file.
  2190.    RECFM             Record format for incoming files.
  2191.    SPACE             Allocation unit (in tracks) for incoming files.
  2192.    UNIT              Device type for incoming files.
  2193. 12.3. Kermit-TSO Subcommands                                             Page 47
  2194. 0-------------------------------------------------------------------------------
  2195.    VOLUME            Disk pack for incoming files.
  2196.  PREFIX              Default disk area.
  2197. 0
  2198.  SET DELIM
  2199. 0Syntax: SET DELIM [letter]
  2200. 0This sets (or clears) a command line delimiter for interactive  Kermit  subcom-
  2201.  mands.    Each occurrence of the delimiter character in the command buffer read
  2202.  from the terminal is treated as the start of a new  subcommand.    The  initial
  2203.  value is a blank, i.e., no delimiter.
  2204. 0
  2205.  SET FILE BLKSIZE
  2206. 0Syntax: SET FILE BLKSIZE number
  2207. 0This  sets  the  block size for incoming files to a number from 1 to 32760.  In
  2208.  the case of fixed-format files, this number is just an upper bound; the  actual
  2209.  block  size  is  taken  to  be the largest multiple of the LRECL which does not
  2210.  exceed this limit.  The default is 6233.
  2211. 0
  2212.  SET FILE LRECL
  2213. 0Syntax: SET FILE LRECL number
  2214. 0This sets the effective logical record length for incoming files  to  a  number
  2215.  from 1 to 32760.  This parameter is not used for files of undefined record for-
  2216.  mat.  The default is 80.
  2217. 0
  2218.  SET FILE RECFM
  2219. 0Syntax: SET FILE RECFM option
  2220. 0This sets the record format to use for  incoming  files.    Valid  options  are
  2221.  "Fixed",  "Varying"  (the  default),  and  "Undefined".  This parameter is thus
  2222.  limited to a subset of the range of possibilities for the MVS/TSO  RECFM.    In
  2223.  Kermit-TSO,  all  incoming  files  of fixed or varying format are automatically
  2224.  blocked according to the current block size.
  2225. 0Note: the most common files with RECFM=U, load modules, cannot  be  transported
  2226.  directly  using  Kermit, since they contain disk-location pointers.  Such files
  2227.  can be "unloaded" using IEHMOVE and then transmitted freely.
  2228. 0
  2229.  SET FILE SPACE
  2230. 0Syntax: SET FILE SPACE number
  2231. 0This sets the track allocation unit for incoming files to a number  from  1  to
  2232.  32760.    The default is 5.  Since data sets are allowed as many as 15 extents,
  2233.  this default provides for files up to 75 tracks.
  2234. 12.3. Kermit-TSO Subcommands                                             Page 48
  2235. 0-------------------------------------------------------------------------------
  2236.  SET FILE UNIT
  2237. 0Syntax: SET FILE UNIT type
  2238. 0This sets the device type or  group  for  incoming  files.    Valid  types  are
  2239.  installation-dependent.  The default is blank, which signifies the default UNIT
  2240.  group found in the User Attribute Data Set.  This parameter should generally be
  2241.  left blank unless the user wishes to create files on a specific disk volume not
  2242.  included in the default group (for example, a private volume).
  2243. 0
  2244.  SET FILE VOLUME
  2245. 0Syntax: SET FILE VOLUME name
  2246. 0This  sets  the  disk  volume  for   incoming   files.      Valid   names   are
  2247.  installation-dependent,  but  are,  in  any case, no more than six alphanumeric
  2248.  characters.  The default is blank (none); in that case, the system chooses  one
  2249.  of the available volumes of the current UNIT type.
  2250. 0
  2251.  SET PREFIX
  2252. 0Syntax: SET PREFIX [string]
  2253. 0This subcommand is equivalent to the CWD subcommand (q.v.).
  2254. 0
  2255.                                THE TAKE SUBCOMMAND
  2256. 0Syntax: TAKE filespec
  2257. 0Execute  Kermit subcommands from the specified file.  The default DSN extension
  2258.  is "TAKE", so that datasets with names of the form prefix.name.TAKE can be  ex-
  2259.  ecuted  by  typing merely TAKE name.  Names that end with .TAKE or .KERMINI are
  2260.  accepted as entered (aside from prefixing), and names in quotes are, of course,
  2261.  accepted exactly as entered, but all others are assumed to have a DSN extension
  2262.  of .TAKE for the purposes of the TAKE (and GIVE) subcommands.
  2263. 0
  2264.                                THE TSO SUBCOMMAND
  2265. 0Syntax: TSO text of command
  2266. 0Although Kermit-TSO does not have a full set of its own subcommands for  manag-
  2267.  ing  TSO  files,  it provides those services through the operating system.  You
  2268.  can issue any TSO command, e.g., to list, type, rename or  delete  files,  send
  2269.  messages,  and  so  on.  The TSO subcommand under Kermit is synonymous with the
  2270.  HOST subcommand.
  2271. 12.4. How to build an executable Kermit-TSO                              Page 49
  2272. 0-------------------------------------------------------------------------------
  2273.  2.4. How to build an executable Kermit-TSO
  2274. 0Before attempting to build Kermit-TSO, look in the  Kermit  distribution  under
  2275.  IKTKER  for  an  installation  document,  as well as "beware", help, and update
  2276.  files, and read them first.  They will probably  contain  information  that  is
  2277.  more current than what you see here.
  2278. 0Kermit-TSO  consists at present of a large assembly (KERMIT.ASM, containing the
  2279.  Kermit program) and a small one (DYNALC.ASM, containing a  subroutine  for  al-
  2280.  locating  data sets).  Although DYNALC is a single file in the Kermit distribu-
  2281.  tion, the source for  Kermit  itself  is  in  many  pieces,  some  generic  for
  2282.  Kermit-370 and some specific to TSO.  All the necessary pieces are sequenced in
  2283.  columns 73-80 so that the numbers form a strictly increasing sequence when  the
  2284.  pieces  are  correctly  "pasted"  together.    It  is important to preserve the
  2285.  original sequence numbers so that updates,  if  any,  can  be  applied  to  the
  2286.  source.
  2287. 0To create a runnable version (the hard way):
  2288. 0   1. Combine  the following "ASM" files from the Kermit distribution into
  2289.        a single file with RECFM=F(B) and LRECL=80: IK0DOC, IK0MAC,  IKTMAC,
  2290.        IK0DEF,  IK0MAI,  IK0COM, IK0CMD, IKTUTL, and IK0PRO.  The resulting
  2291.        file is the composite  source  for  Kermit-TSO,  called  KERMIT.ASM.
  2292.        This  source  must  retain  the original sequence numbers in columns
  2293.        73-80 (in other words, be sure not to resequence the source acciden-
  2294.        tally by using the editor!)
  2295. 0   2. Copy  or  rename  IKTDYN.ASM  from the Kermit distribution to a file
  2296.        called DYNALC.ASM with RECFM=F(B) and LRECL=80.
  2297. 0   3. Assemble the source file(s).
  2298. 0   4. Create the executable load module KERMIT using the  linkage  editor.
  2299.        Be  sure to specify the REUS option.  Kermit is designed to run as a
  2300.        command processor, and so it must be placed in SYS1.CMDLIB or  in  a
  2301.        PDS  concatenated  to SYS1.CMDLIB (for example, via the STEPLIB com-
  2302.        mand).
  2303. 0To create a runnable version the easy way, extract the batch job from  the  in-
  2304.  stallation document, supply a proper JOB card, and submit it.
  2305. 0If your site's ASCII/EBCDIC translation table for TTY lines does not conform to
  2306.  the one listed in the appendix (which in turn conforms to the one given in  the
  2307.  IBM   System/370   Reference   Summary),   then   enter   the  appropriate  SET
  2308.  ATOE/ETOA/TATOE/TETOA  subcommands  into  'SYS1.KERMINI'.      NOTE:   If   the
  2309.  ASCII/EBCDIC translation is not invertible, Kermit will not and cannot work.
  2310. 0In order to verify the operation of a new version of Kermit-TSO, you may run it
  2311.  under TEST using the CP parameter.
  2312. 12.5. What's New                                                         Page 50
  2313. 0-------------------------------------------------------------------------------
  2314.  2.5. What's New
  2315. 0Below is a list of the TSO-specific features in  Version  4.2.0  of  Kermit-TSO
  2316.  added  since  the previous major release, Version 4.1 in January 1989.  For the
  2317.  list of generic additions, see the chapter on Kermit-370.
  2318. 0   1. Implicit CLIST invocation now supported.
  2319. 0   2. Missing host commands no longer result in ABEND's.    Kermit  simply
  2320.        returns an "invalid host command" indication.
  2321. 0   3. Migrated  data  sets are automatically recalled, if possible, before
  2322.        attempting to use them.  This includes especially the initialization
  2323.        files.
  2324. 0   4. Sending PDS members by wildcard has been re-enabled.
  2325. 0   5. The  "MOD"  date, as defined by ASM2 package, is now used (if it ex-
  2326.        ists) instead of the creation date for sending the date attribute.
  2327. 0   6. Host commands may now be up to 256 bytes long and be mixed-case.
  2328. 0   7. NOINTERCOM is set during transfers.
  2329. 0   8. Avoid truncating foreign filespec for GET/SEND.
  2330. 0   9. Automatic detection of VTAMTTY as opposed to plain TTY.
  2331. 0  10. TTY-mode timeouts now work under MVS/XA and MVS/ESA.
  2332. 0  11. Kermit HELP subcommand now works more than once per session.
  2333. 0
  2334.  2.6. What's Missing
  2335. 0Work on Kermit-TSO will continue.  Features that need to be improved  or  added
  2336.  include:
  2337. 0   - Add support for IBM 3174 AEA transparent mode.
  2338. 0   - Intercept ABEND's in TSO commands executed under Kermit.
  2339. 0   - Implement file archiving.
  2340. 0   - Add a SET REPEAT subcommand.
  2341. 0   - Finish  SET  LINE,  so that Kermit-TSO can be used as a local Kermit,
  2342.       connecting to a remote host over  an  alternate  communication  port.
  2343.       Add a CONNECT subcommand.
  2344. 0   - Compute file size for outgoing A-packets and implement the SPACE sub-
  2345.       command.
  2346. 0   - Reject files known (via  A-packets)  to  be  too  big  for  available
  2347.       storage.
  2348. 0   - Intercept all terminal output during protocol mode.
  2349. 1IBM System/370 Kermit                                                   Page 51
  2350. 0-------------------------------------------------------------------------------
  2351.  Anyone interested in working on these or other improvements should first get in
  2352.  touch with the Center for Computing Activities at Columbia University  to  find
  2353.  out if someone else has already begun a similar project (and, if so, who).
  2354. 1IBM System/370 Kermit                                                   Page 52
  2355. 0-------------------------------------------------------------------------------
  2356.  Index
  2357. 0          3174   1, 16                    Electronic mail   8
  2358.            3708   16                       End of file   19
  2359.                                            Error codes   35
  2360.            Alternate lines   23            Extended ASCII   15
  2361.            Appending   20
  2362.            ASCII-to-EBCDIC   15            File attributes   2, 16, 29
  2363.            Attributes.   See   File   at-  File disposition   8
  2364.                    tributes                File renaming   20
  2365.                                            File truncation   19
  2366.            Batch jobs   8                  Filename collision   20, 45
  2367.            Binary files   1, 12, 21        Flow control   31
  2368.            Blanks                          Folding   12, 21, 45
  2369.               preserving trailing   22     Foreign   9, 22
  2370.               stripping   2, 22, 23        Front end   1
  2371.               trailing   2, 23             Full screen   11, 31
  2372.            BLKSIZE   2
  2373.            Block check   16                GET   10
  2374.                                            GIVE   11, 48
  2375.            Cancelling  a  file   transfer  Greek   3, 25
  2376.                    13
  2377.            Catalog   40                    Handshake   22, 31
  2378.            Character sets   3, 19, 25, 26  Hebrew   3, 25
  2379.            CICS   18, 20                   HELP   45
  2380.            CLIST   43                      Host commands   11, 24
  2381.            CMS   18, 20
  2382.            Code pages   3                  IBM   1, 40
  2383.                 See also   Character sets  Incomplete files   12, 23
  2384.            Collision.  See  Filename col-  Initialization  files    2, 7,
  2385.                    lision                          8, 20, 25, 27, 39, 42,
  2386.            Command echoing   25, 31                49
  2387.            Command prefix   9, 11, 24
  2388.            Completion codes   35           Kanji   3, 20, 25
  2389.                 See also   Error codes     Katakana   3, 25
  2390.            Controller   16
  2391.            CRLF   2, 21                    Languages   3
  2392.            CSW   18                        Line delimiter   47
  2393.            CWD   44                        Load modules   47
  2394.            Cyrillic   3, 20, 25            Local   9
  2395.                                            LOCAL-ECHO   31
  2396.            Data set. See File              Log files   39
  2397.            DCB. See File attributes        Long packets   12, 27, 30
  2398.            Debugging   17                  LRECL   2, 22, 39
  2399.            DIRECTORY   45
  2400.            Discarding files   20, 23, 37   Mail   8
  2401.                 See also   DELETE               See  also      Electronic
  2402.            DOS-4   2                               mail
  2403.            Dumping storage   17            Margins   23
  2404.                                            MTS   2
  2405.            EBCDIC-to-ASCII   15            MUSIC   18, 20
  2406.            ECHO   10                       MVS/TSO   40
  2407.                 See also   Command  echo-
  2408.                    ing                     Optimum packet size   13, 24
  2409.            Eighth-bit prefix   26, 28      Overwriting files   21
  2410. 1IBM System/370 Kermit                                                   Page 53
  2411. 0-------------------------------------------------------------------------------
  2412.                 See also   Filename  col-          25, 49
  2413.                    lision                  Transparent mode   10, 31
  2414.                                            Truncation   12, 21, 45
  2415.            Packet size   13, 27                 See  also      File trun-
  2416.            Parity   28, 31                         cation
  2417.            Partitioned data set   40       TSO   18, 20, 39
  2418.            Passwords   42                  TTY   1, 16, 31, 40
  2419.            Prefix.      See      Command,  Type   12, 14
  2420.                    Eighth-bit, Foreign
  2421.            Prefix   44, 48                 Uncataloged data sets   41
  2422.            Printing files   8              User profile   42, 44
  2423.            Prompt   23
  2424.                                            Warning   20
  2425.            Qualifier   40                  Wildcards   41, 46
  2426.            Quote. See Prefix
  2427.                                            XECHO   10
  2428.            Raw transmission   10, 31
  2429.            RECEIVE   10, 12, 45
  2430.            RECFM   2
  2431.            Records   2
  2432.            Remote   9
  2433.            RENAME   20
  2434.            Renaming files   20
  2435.                 See also   File renaming
  2436.            ROSCOE   18, 20
  2437. 0          Screen refresh   32
  2438.            SEND   10, 12, 46
  2439.            SEND delay   19
  2440.            Series/1   1, 16, 40
  2441.            SERVER   13
  2442.            SET   14, 46
  2443.            SHOW   29
  2444.            SNA   1, 16
  2445.            STATUS   30
  2446.            STOP   30
  2447.            Stripping blanks. See Blanks
  2448.            Subcommand prefix. See Command
  2449.                    prefix
  2450.            Submitting jobs   8
  2451.                 See also   Batch jobs
  2452. 0          Tabs   24
  2453.            TAKE   31, 48
  2454.            TDUMP   31
  2455.            TEST   25
  2456.            TGET   18
  2457.            Timeout   24, 29, 32
  2458.            TPUT   18
  2459.            Tracing execution   18
  2460.            Trailing blanks. See Blanks
  2461.            Trailing   blanks,  preserving
  2462.                    46
  2463.            Transaction log   12, 31
  2464.            Translation   1, 3, 26
  2465.            Translation tables     3,  11,
  2466. +
  2467.